diff --git a/.idea/.idea.GridCasting/.idea/.gitignore b/.idea/.idea.GridCasting/.idea/.gitignore new file mode 100644 index 0000000..3fd64fa --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/.gitignore @@ -0,0 +1,13 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Rider ignored files +/projectSettingsUpdater.xml +/.idea.GridCasting.iml +/modules.xml +/contentModel.xml +# Editor-based HTTP Client requests +/httpRequests/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml diff --git a/.idea/.idea.GridCasting/.idea/copilot.data.migration.agent.xml b/.idea/.idea.GridCasting/.idea/copilot.data.migration.agent.xml new file mode 100644 index 0000000..4ea72a9 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/copilot.data.migration.agent.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/copilot.data.migration.ask.xml b/.idea/.idea.GridCasting/.idea/copilot.data.migration.ask.xml new file mode 100644 index 0000000..7ef04e2 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/copilot.data.migration.ask.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/copilot.data.migration.ask2agent.xml b/.idea/.idea.GridCasting/.idea/copilot.data.migration.ask2agent.xml new file mode 100644 index 0000000..1f2ea11 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/copilot.data.migration.ask2agent.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/copilot.data.migration.edit.xml b/.idea/.idea.GridCasting/.idea/copilot.data.migration.edit.xml new file mode 100644 index 0000000..8648f94 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/copilot.data.migration.edit.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/discord.xml b/.idea/.idea.GridCasting/.idea/discord.xml new file mode 100644 index 0000000..30bab2a --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/discord.xml @@ -0,0 +1,7 @@ + + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/encodings.xml b/.idea/.idea.GridCasting/.idea/encodings.xml new file mode 100644 index 0000000..df87cf9 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/encodings.xml @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/indexLayout.xml b/.idea/.idea.GridCasting/.idea/indexLayout.xml new file mode 100644 index 0000000..7b08163 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/indexLayout.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/.idea.GridCasting/.idea/vcs.xml b/.idea/.idea.GridCasting/.idea/vcs.xml new file mode 100644 index 0000000..773e715 --- /dev/null +++ b/.idea/.idea.GridCasting/.idea/vcs.xml @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/GridCasting.sln b/GridCasting.sln index 0f85bb1..e5e74a9 100644 --- a/GridCasting.sln +++ b/GridCasting.sln @@ -8,6 +8,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GuidingTurtle", "..\Igdrasi EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "IgdrasilEngine", "IgdrasilEngine", "{41458A8F-715B-405E-84E2-140989D50977}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GridCastingTests", "GridCastingTests\GridCastingTests.csproj", "{D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SapphireCodegen", "..\IgdrasilEngine\SapphireCodegen\SapphireCodegen.csproj", "{66C444B7-F9D3-4C6A-A7A2-E2443C7342AE}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -26,9 +30,18 @@ Global {2575A7D5-2936-4823-A0B4-A466790D70B5}.Debug|Any CPU.Build.0 = Debug|Any CPU {2575A7D5-2936-4823-A0B4-A466790D70B5}.Release|Any CPU.ActiveCfg = Release|Any CPU {2575A7D5-2936-4823-A0B4-A466790D70B5}.Release|Any CPU.Build.0 = Release|Any CPU + {D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA}.Debug|Any CPU.Build.0 = Debug|Any CPU + {D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA}.Release|Any CPU.ActiveCfg = Release|Any CPU + {D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA}.Release|Any CPU.Build.0 = Release|Any CPU + {66C444B7-F9D3-4C6A-A7A2-E2443C7342AE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {66C444B7-F9D3-4C6A-A7A2-E2443C7342AE}.Debug|Any CPU.Build.0 = Debug|Any CPU + {66C444B7-F9D3-4C6A-A7A2-E2443C7342AE}.Release|Any CPU.ActiveCfg = Release|Any CPU + {66C444B7-F9D3-4C6A-A7A2-E2443C7342AE}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(NestedProjects) = preSolution {2575A7D5-2936-4823-A0B4-A466790D70B5} = {41458A8F-715B-405E-84E2-140989D50977} {10E6C5FC-990E-429E-9635-E4F639FF6B9D} = {41458A8F-715B-405E-84E2-140989D50977} + {66C444B7-F9D3-4C6A-A7A2-E2443C7342AE} = {41458A8F-715B-405E-84E2-140989D50977} EndGlobalSection EndGlobal diff --git a/GridCasting.sln.DotSettings.user b/GridCasting.sln.DotSettings.user new file mode 100644 index 0000000..df35dda --- /dev/null +++ b/GridCasting.sln.DotSettings.user @@ -0,0 +1,12 @@ + + ForceIncluded + ForceIncluded + ForceIncluded + ForceIncluded + ForceIncluded + <SessionState ContinuousTestingMode="0" IsActive="True" Name="Test" xmlns="urn:schemas-jetbrains-com:jetbrains-ut-session"> + <TestAncestor> + <TestId>NUnit3x::D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA::net8.0::GridCastingTests.GridResolverTests</TestId> + <TestId>NUnit3x::D109D2B9-B2DD-43CE-8FA7-7E118BCF16EA::net8.0::GridCastingTests.ExecutorTests</TestId> + </TestAncestor> +</SessionState> \ No newline at end of file diff --git a/GridCasting/Docs/project.md b/GridCasting/Docs/Reports/project.md similarity index 99% rename from GridCasting/Docs/project.md rename to GridCasting/Docs/Reports/project.md index e131f0f..5fb4f31 100644 --- a/GridCasting/Docs/project.md +++ b/GridCasting/Docs/Reports/project.md @@ -1,3 +1,6 @@ +--- +order: 0 +--- УДК 004.4 {.compact} diff --git a/GridCasting/Docs/tech.md b/GridCasting/Docs/Reports/tech.md similarity index 99% rename from GridCasting/Docs/tech.md rename to GridCasting/Docs/Reports/tech.md index 13c8229..51b6145 100644 --- a/GridCasting/Docs/tech.md +++ b/GridCasting/Docs/Reports/tech.md @@ -1,3 +1,7 @@ +--- +order: 0 +--- + УДК 004.4 {.compact} Отчёт по технологической практике по образовательной программе «Разработка и дизайн компьютерных игр и мультимедийных приложений» направления подготовки «Программная инженерия» на тему «Инструментальная библиотека распознавания и исполнения символьных команд в игровых механиках» / Исполнитель: Измайлов А.Р.: М. 2026 г., 2026 {.compact} diff --git a/GridCasting/Docs/Reports/tech_section_3.md b/GridCasting/Docs/Reports/tech_section_3.md new file mode 100644 index 0000000..bb85a32 --- /dev/null +++ b/GridCasting/Docs/Reports/tech_section_3.md @@ -0,0 +1,109 @@ +--- +order: 0 +--- + +## 3. ТЕХНОЛОГИЧЕСКИЙ РАЗДЕЛ + +### Введение + +Настоящий раздел посвящен технологической реализации библиотеки GridCasting, предназначенной для распознавания и исполнения символьных команд, задаваемых пользователем на графовой сетке. В отличие от игровой сцены или законченного прикладного продукта, объектом рассмотрения здесь выступает именно библиотечное ядро: набор структур данных и алгоритмов, обеспечивающих переход от последовательности координат пользовательского ввода к дискретному маршруту, а затем к выбору и запуску соответствующей команды. Такая постановка важна, поскольку технологическая практика в данном проекте была ориентирована не на создание визуального контента, а на проверку работоспособности ключевых программных механизмов, предложенных на этапе проектирования. + +По результатам проектной практики была сформулирована задача разработки универсальной библиотеки, способной работать не только с одной фиксированной геометрией сетки, но и с произвольной графовой топологией. На этапе технологической реализации эта задача была конкретизирована в виде нескольких практических направлений: создание модели графовой сетки, построение механизма локализации координат в узлы графа, формирование маршрута по последовательности точек, сопоставление полученного паттерна с командой и подготовка расширяемого контура исполнения. При этом существенным требованием оставалось сохранение модульности архитектуры, чтобы библиотека могла использоваться в игровых и иных интерактивных приложениях без жесткой привязки к конкретному движку или интерфейсному слою. + +Фактическая реализация, представленная в репозитории, подтверждает достижение промежуточного, но значимого результата. В коде уже присутствуют основные модели данных, пространственный индекс, механизм построения пути и подсистема сопоставления маршрута с командой. Вместе с тем полный сквозной цикл обработки ввода еще не завершен: метод `GridCasting.Execute()` выполняет только начальный этап работы, а интерфейс трансформации паттернов пока не получил конкретных реализаций. Поэтому в дальнейшем изложении библиотека рассматривается как работоспособный прототип ядра, а не как полностью завершенный программный продукт. + +### 3.1. Обоснование выбора средств разработки проекта в целом + +Выбор средств разработки определялся характером решаемой задачи. Поскольку проект связан с обработкой структурированных данных, геометрических преобразований и построением расширяемого программного интерфейса, требовалась среда, которая сочетала бы строгую типизацию, приемлемую производительность и удобство интеграции с внешними системами. По этой причине в качестве основного языка реализации был выбран C#, а в качестве платформы исполнения - .NET 8. + +Использование C# представляется обоснованным прежде всего с точки зрения архитектурной дисциплины. Библиотека содержит несколько слоев, отличающихся по назначению: модель графовой сетки, алгоритмы локализации и преобразования пути, исполнительный контур команд, а также вспомогательные структуры данных. В таких условиях статическая типизация играет не только роль средства проверки корректности кода, но и становится инструментом проектирования API. Это особенно заметно в интерфейсах `ICommand`, `IEnvironmentResolver` и `IPathTransform`, которые задают границы расширения библиотеки и позволяют описывать пользовательскую интеграцию в явном и контролируемом виде. Дополнительным преимуществом является включенная в проект поддержка nullable-типов, уменьшающая число скрытых ошибок при работе со ссылочными объектами. + +Платформа .NET 8 выбрана как среда, обеспечивающая современный уровень кроссплатформенности и достаточно высокую производительность для задач, связанных с обработкой пользовательского ввода. Хотя текущая реализация еще не интегрирована в конкретное приложение, сама библиотека ориентирована на повторное использование в различных программных средах. В этом контексте .NET удобен тем, что не ограничивает разработчика рамками одного игрового движка или одной операционной системы. Кроме того, стандартный стек сборки на базе SDK-проекта и MSBuild делает структуру решения достаточно прозрачной и пригодной для дальнейшего сопровождения. + +Отдельно следует отметить выбор версии языка. В файле проекта установлено значение `LangVersion: preview`, что позволяет использовать современные синтаксические средства C#, включая первичные конструкторы и сокращенные формы объявления объектов. Для рассматриваемого проекта это не является самоцелью, однако упрощает описание компактных сущностей и снижает объем шаблонного кода. В результате текст программы лучше отражает собственно алгоритмическую логику, а не рутинные детали инициализации. + +С технологической точки зрения важную роль играет и внешняя математическая зависимость `IgdrasilMath`, подключенная как проектная ссылка. Поскольку библиотека активно работает с двумерными векторами, ограничивающими прямоугольниками и базовыми геометрическими операциями, повторная реализация таких примитивов внутри GridCasting была бы избыточной. Использование уже существующего математического модуля позволило сосредоточиться именно на специфике распознавания графовых паттернов, а не на низкоуровневой геометрической инфраструктуре. + +### 3.2. Обоснование выбора инструментальных средств разработки для отдельных элементов + +На уровне отдельных компонентов выбор инструментальных средств определялся уже не общими свойствами платформы, а особенностями обрабатываемых данных и типом операций, которые библиотека должна выполнять. В результате технологическая реализация строится вокруг нескольких ключевых структур, каждая из которых решает строго определенный класс задач. + +Базовой абстракцией служит `GridGraph`. Выбор графовой модели вместо жестко заданной квадратной или шестиугольной сетки продолжает логику, сформулированную еще на проектном этапе. Такая модель позволяет отделить топологию связей между узлами от конкретного способа визуального представления сетки. Класс `GridGraphNode` хранит набор исходящих ребер, а `GridGraphEdge` дополняет сам факт связи геометрическими параметрами - длиной и углом. Благодаря этому система способна не просто фиксировать соседство узлов, но и интерпретировать его в терминах перемещения в пространстве. Для целей библиотеки это принципиально: пользовательский ввод поступает в виде координат, а значит, сетка должна быть одновременно графовой по структуре и геометрической по способу локализации. + +Следующим важным элементом является `GridResolver`. Его роль состоит в том, чтобы связать непрерывное координатное представление пользовательского ввода с дискретной структурой графа. Формально эта задача может быть разложена на несколько этапов - поиск ближайшей вершины, проверка допустимости перехода, кодирование направления, формирование маршрута, - однако в практической реализации они объединены в один компонент. Это решение оправдано тем, что все перечисленные операции опираются на один и тот же набор данных: текущую вершину графа, положение в двумерном пространстве и чувствительность локализации. В результате `GridResolver` выступает не просто преобразователем координат, а центральным технологическим узлом всей библиотеки. + +Для ускорения пространственного поиска выбран индекс `PointBVH2D`. Необходимость такой структуры обусловлена тем, что прямой перебор всех узлов графа при каждом новом положении указателя или касания быстро стал бы узким местом при масштабировании сетки. BVH-дерево позволяет организовать поиск ближайших точек в пределах заданного радиуса более эффективно, чем линейный просмотр, и тем самым делает алгоритм пригодным для сценариев интерактивного ввода. Важно и то, что в данной реализации BVH применяется не абстрактно, а именно в связке с графом: сначала индекс помогает найти опорную точку в пространстве, а затем логика `GridResolver` продолжает поиск уже по структуре связей между вершинами. + +Для хранения и поиска команд используется обобщенная структура `Trie`. Ее применение оправдано тем, что паттерн команды в библиотеке представлен конечной последовательностью целых чисел, описывающих начальный узел и набор локальных направлений. Такая запись естественным образом соотносится с префиксным деревом. В отличие от простого словаря, trie позволяет удобно хранить паттерны с общими префиксами, а также поддерживать логику слабых листьев, что в будущем может быть полезно для семейства сходных маршрутов. В `PathExecutor` эта структура используется как внутреннее хранилище отображения пути в объект команды. + +Наконец, слой исполнения основан на сочетании `PathExecutor`, `ICommand`, `CommandContext`, `IEnvironmentResolver` и `ListenableDictionary`. Здесь выбор инструментов подчинен задаче отделения распознавания команды от ее фактического действия. Сам по себе обнаруженный маршрут еще не несет прикладного эффекта; такой эффект возникает только тогда, когда библиотека передает найденную команду во внешний контекст. Интерфейс `ICommand` делает этот переход явным, а `CommandContext` задает набор данных, которые команда получает при запуске: распознанный путь, словарь окружения и стек исполнения. В свою очередь, `ListenableDictionary` и резолверы окружения формируют реактивную прослойку между внутренним состоянием исполнительного контура и внешней средой приложения. За счет этого библиотека приобретает свойства интеграционного инструмента, а не только алгоритмического модуля. + +### 3.3. Описание реализации технологического контура библиотеки + +Практическая реализация библиотеки строится вокруг технологического контура обработки пользовательского ввода. В проекте отсутствует отдельный слой визуализации, поэтому основным предметом описания становится именно последовательность программных процессов, обеспечивающих переход от массива координат к потенциальному вызову команды. + +Первым этапом является построение внутреннего представления сетки. Для этого используются классы `GridGraph`, `GridGraphNode` и `GridGraphEdge`. Каждый узел содержит список ребер, а каждое ребро определяет связь между двумя узлами, ее длину и угол. Такая организация позволяет описывать сетку как в терминах дискретной топологии, так и в терминах размещения в двумерном пространстве. Дополнительно в проекте сохранен более простой слой `Grid` и `GridNode`, который может использоваться для генерации сеточных представлений в ограниченном диапазоне, однако основным рабочим форматом для алгоритмов распознавания выступает именно граф. + +После построения графовой модели выполняется подготовка пространственного индекса. При создании `GridResolver` граф обходится, для каждой достигнутой вершины вычисляется ее позиция в дереве обхода, и эти точки добавляются в `PointBVH2D`. Одновременно формируется ограничивающий прямоугольник всей структуры. На практике это означает, что библиотека заранее подготавливает пространственную карту опорных точек, с которыми в дальнейшем сопоставляется пользовательский ввод. Такое решение переносит значительную часть вычислительной нагрузки из онлайн-обработки в стадию инициализации. + +Третий этап связан с локализацией пользовательских координат. Метод `GetPath` получает массив `FVector2` и начинает с поиска ближайшей опорной точки для первой координаты. Если точка не найдена либо найдено несколько равноценных кандидатов, формирование маршрута не продолжается. Далее система последовательно проверяет, соответствует ли каждая следующая координата одному из допустимых переходов из текущего узла графа. Иначе говоря, ввод интерпретируется не как произвольная кривая, а как попытка пройти по существующим ребрам дискретной структуры. При успешном прохождении каждого шага библиотека фиксирует индекс локального направления и в итоге формирует объект `Path`, содержащий стартовый узел и массив направлений. + +Следующий процесс относится уже к исполнительному слою. В `PathExecutor` зарегистрированные команды сохраняются по своим паттернам, после чего путь может быть использован как ключ для поиска нужного действия. При успешном совпадении создается объект `CommandContext`, который объединяет распознанный путь, окружение и стек выполнения. Именно в этот момент путь из чисто алгоритмического результата превращается в основание для прикладной логики. + +Особое место в этом контуре занимает механизм трансформаций пути. В архитектуре библиотеки предусмотрен интерфейс `IPathTransform`, а класс `GridCasting` принимает набор таких трансформаций как параметр конструктора. Это означает, что нормализация, реверс или иные преобразования паттерна изначально рассматриваются как расширяемый этап конвейера. Однако в текущем состоянии проекта эта часть является заготовкой архитектурного уровня: конкретные реализации трансформов в репозитории отсутствуют, а метод `GridCasting.Execute()` пока ограничивается вызовом `_resolver.GetPath(positions)`. Следовательно, технологический контур в его полном проектном виде лишь частично завершен, хотя ключевые подсистемы для него уже созданы. + +### 3.4. Описание реализованных механизмов + +С точки зрения фактической реализации можно выделить несколько механизмов, составляющих ядро библиотеки. Первый из них - графовое представление сетки. В данной модели направление перемещения задается не абсолютными координатами на экране, а индексом ребра относительно текущего узла. Это позволяет кодировать маршрут как дискретную последовательность решений на графе. Такой подход особенно важен для библиотечного решения, рассчитанного на разные типы сеток: он переносит акцент с внешней геометрической формы на внутреннюю структуру переходов. + +Второй механизм связан с алгоритмом построения пути в `GridResolver.GetPath`. Его работа основана на сочетании пространственной локализации и топологической валидации маршрута. Первая координата задает стартовую точку, после чего каждая следующая координата должна соответствовать одному из геометрически допустимых переходов из текущего узла. Если такой переход найден, в маршрут записывается индекс ребра, а текущее состояние сдвигается на следующую вершину. Если переход не найден, метод немедленно возвращает `null`. Тем самым библиотека уже на этапе построения пути отсекает ввод, не соответствующий структуре графа. + +Третий механизм - поиск ближайшей точки через BVH. Метод `GetNearestPoint` сначала пытается найти вершину в пределах заданной чувствительности по уже построенному индексу. Если однозначного совпадения нет, применяется расширенный поиск с обходом графовых соседей и приоритетной очередью. Это решение показывает, что пространственная локализация в библиотеке не сводится к простому обращению к индексу, а дополняется логикой обхода и уточнения положения. В практическом смысле это делает компонент более устойчивым к вариативности размещения графовых точек. + +Четвертый механизм реализован в `Trie` и `PathExecutor`. Путь, представленный как последовательность целых чисел, используется для точного сопоставления с зарегистрированной командой. При этом `Path` реализует `IEnumerable`, что упрощает его преобразование в массив ключей для trie-структуры. Если совпадение найдено, команда вызывается через общий интерфейс `ICommand`. Благодаря этому распознавание паттерна и прикладное действие остаются разделенными, но технологически связанными. + +Пятый механизм относится к управлению окружением исполнения. Внутри `PathExecutor` хранится словарь переменных окружения, обернутый в `ListenableDictionary`, а также карта резолверов, отвечающих за загрузку, обновление и сброс значений. Это решение позволяет командам работать не в изоляции, а в контексте внешнего состояния. Для будущей интеграции с игрой или интерактивным приложением такой механизм принципиален: он подготавливает библиотеку к сценарию, в котором распознанная команда должна изменять состояние персонажа, сцены, интерфейса или иного объекта внешней системы. + +### 3.5. Описание реализованного программного пространства + +В типовом плане технологической практики для игрового проекта обычно рассматривается игровое пространство как совокупность сцены, объектов, анимаций и пользовательских экранов. В случае GridCasting такой подход неприменим, поскольку текущая реализация не содержит самостоятельной визуальной среды. Поэтому в рамках настоящего отчета корректнее говорить не об игровом, а о программном пространстве библиотеки. + +Это пространство образовано несколькими взаимосвязанными слоями. Нижний уровень составляют модели данных `Grid`, `GridNode`, `GridGraph`, `GridGraphNode`, `GridGraphEdge` и `Path`, задающие формальное представление сетки и маршрута. Над ними расположен слой алгоритмической обработки, включающий `GridResolver` и BVH-инфраструктуру. Еще выше находится исполнительный слой, где размещены `PathExecutor`, `ICommand`, `CommandContext`, `IEnvironmentResolver` и вспомогательный реактивный словарь состояния. Поток данных проходит через эти слои последовательно: массив координат преобразуется в путь, путь используется для поиска команды, команда получает контекст исполнения. + +Такое программное пространство уже позволяет проследить предполагаемый жизненный цикл команды внутри внешнего приложения. Однако репозиторий не содержит пользовательского интерфейса, отдельной сцены, экранных форм, визуальных индикаторов распознавания или средств демонстрации результата на уровне конечного пользователя. Из этого следует важный вывод: реализованная система на текущем этапе представляет собой библиотечное ядро для последующего встраивания в приложение, а не самостоятельный продукт с законченным пользовательским сценарием. + +### 3.6. Первичная проверка полученной реализации + +Первичная проверка разрабатываемой библиотеки проводилась на уровне анализа исходного кода, проверки реализованных сценариев обработки и попытки компиляции проекта в локальной среде разработки. Поскольку в репозитории отсутствует выделенный тестовый проект с автоматизированными модульными тестами, подтверждение работоспособности на данном этапе носит характер разработческой верификации отдельных подсистем, а не строгого экспериментального доказательства полной функциональной завершенности. + +Первый проверочный сценарий относится к корректности представления сетки произвольной топологии. Для этой цели в `GridResolver` реализован метод `VerifyGridGraph`, который выполняет обход графа и сопоставляет каждой достигнутой вершине вычисленную пространственную позицию. Если одна и та же вершина оказывается связана с несовместимыми координатами, проверка прерывается. Наличие такого механизма позволяет сделать вывод, что в библиотеке уже предусмотрена внутренняя валидация согласованности графовой структуры. + +Второй сценарий связан с преобразованием координат в маршрут. Метод `GetPath` реализует явную логику последовательного перехода от первой найденной вершины к следующей по допустимым ребрам графа. Ожидаемым результатом при корректном вводе является формирование объекта `Path`, содержащего стартовый узел и массив индексов направлений. Получаемый в коде результат соответствует этому ожиданию: маршрут формируется только тогда, когда каждая следующая координата может быть интерпретирована как допустимый переход по существующему ребру. В противном случае метод возвращает `null`, что одновременно служит механизмом обнаружения ошибочного ввода. + +Третий сценарий относится к работе пространственного индекса. В `PointBVH2D` реализован поиск ближайших точек в заданном радиусе, а `GridResolver.GetNearestPoint` дополняет его обработкой неоднозначных случаев и пошаговым графовым уточнением. Это позволяет считать подтвержденной работоспособность базового механизма локализации координаты в сетку. Следует, однако, подчеркнуть, что такая проверка опирается на структуру и логику кода; количественные характеристики производительности в текущем репозитории не зафиксированы отдельными бенчмарками. + +Четвертый сценарий касается сопоставления маршрута с командой. В `PathExecutor` реализованы методы добавления команды по паттерну и последующего поиска по маршруту через `Trie`. Если путь найден в дереве, создается `CommandContext` и вызывается метод `Execute` у соответствующей команды. Это означает, что связка "паттерн - действие" уже функционирует на уровне внутренней исполнительной модели. + +Пятый сценарий относится к окружению исполнения. Реализованные обработчики `OnUpdate`, `OnRemove`, `OnClear`, а также подписка на события резолверов показывают, что изменения состояния могут быть синхронизированы с логикой внешней среды. Таким образом, библиотека подготовлена к интеграции с приложением, где команды должны взаимодействовать с изменяемым контекстом, а не только с самим маршрутом. + +Вместе с тем проведенная проверка выявила и ряд ограничений. Полный интеграционный сценарий от массива координат до исполнения команды через публичный метод `GridCasting.Execute()` на данный момент не завершен, поскольку сам метод пока не передает построенный путь в исполнительный слой и не применяет к нему трансформации. Интерфейс `IPathTransform` существует, но конкретные алгоритмы нормализации и реверса паттернов отсутствуют. Кроме того, в текущей реализации не предусмотрена явная обработка пустого массива координат в `GetPath`, что оставляет потенциальный граничный случай для последующей доработки. Наконец, попытка локальной сборки проекта показала, что в используемой среде имеются внешние ограничения конфигурации .NET SDK и workload-резолверов, поэтому успешная компиляция всего решения не была подтверждена в полном объеме именно в данной конфигурации рабочего окружения. + +В совокупности это позволяет сделать сдержанный вывод: технологическая практика обеспечила реализацию и первичную проверку основных алгоритмических компонентов библиотеки, однако полноценная сквозная валидация всего цикла обработки ввода и исполнения команд остается задачей следующего этапа разработки. + +### Предложение дальнейшего развития и доработок продукта + +Логика дальнейшего развития проекта естественным образом вытекает из выявленных ограничений. В первую очередь требуется завершить публичный метод `GridCasting.Execute()`, чтобы он перестал быть только точкой входа в резолвер и начал связывать между собой все уже существующие подсистемы: построение пути, применение трансформаций, поиск команды и передачу управления в исполнительный контур. После этого библиотека сможет выступать не только как набор совместимых компонентов, но и как целостный программный конвейер. + +Вторым направлением развития является наполнение интерфейса `IPathTransform` конкретными реализациями. На уровне архитектуры уже заложена возможность нормализации паттернов, инвариантности к поворотам, обращения маршрута и других преобразований, однако именно эта часть пока отсутствует в коде. Для исследовательской ценности проекта этот этап особенно важен, поскольку он напрямую связан с проверкой исходной гипотезы о возможности независимого от геометрии сопоставления символьных команд. + +Третье направление связано с качеством проверки. Поскольку в текущем репозитории отсутствуют автоматизированные модульные и интеграционные тесты, следующая стадия разработки должна включать формирование тестового контура. Желательно выделить тесты для графовой валидации, BVH-поиска, построения пути, точного сопоставления команд и обработки граничных случаев. Дополнительно представляется целесообразным ввести отдельные сценарии измерения производительности на графах разного размера. + +Наконец, для практической применимости библиотеки потребуется демонстрационный слой интеграции. Это может быть минимальное приложение или модуль для игрового движка, который будет отвечать за сбор пользовательского ввода, визуальное отображение маршрута и вызов публичного API GridCasting. Такое расширение не только улучшит презентацию результата, но и позволит проверить библиотеку в условиях, приближенных к реальному использованию. + +### Заключение + +Технологическая реализация проекта GridCasting показала, что основные архитектурные идеи, сформулированные на проектном этапе, могут быть воплощены в виде программного ядра. В репозитории реализованы графовая модель сетки, пространственный индекс для локализации ввода, алгоритм построения маршрута, структура сопоставления маршрутов с командами и исполнительный контур, ориентированный на интеграцию с внешней средой. Эти результаты позволяют рассматривать библиотеку как работоспособный прототип, пригодный для дальнейшего развития. + +В то же время текущая стадия проекта не дает оснований утверждать, что полный цикл распознавания и исполнения символьных команд завершен окончательно. Нормализация паттернов пока только подготовлена архитектурно, публичный метод исполнения не доведен до конца, автоматизированный тестовый контур отсутствует, а визуальный слой не реализован. Поэтому наиболее корректной характеристикой достигнутого результата является формулировка о создании частично завершенного, но функционально содержательного библиотечного ядра. + +С практической точки зрения проделанная работа имеет значение как основание для дальнейшей выпускной квалификационной разработки. Она уже демонстрирует применимость графового подхода к задаче распознавания символьных команд и одновременно выявляет те участки, где необходимы дополнительные алгоритмические и интеграционные исследования. diff --git a/GridCasting/Docs/Reports/tech_updated.md b/GridCasting/Docs/Reports/tech_updated.md new file mode 100644 index 0000000..90c1cf8 --- /dev/null +++ b/GridCasting/Docs/Reports/tech_updated.md @@ -0,0 +1,543 @@ +--- +order: 0 +--- + +# Текст для отчета по технологической практике + +## Реферат + +ГРАФОВЫЕ ПАТТЕРНЫ, СИМВОЛЬНЫЕ КОМАНДЫ, ИНТЕРАКТИВНЫЕ ПРИЛОЖЕНИЯ, ГРАФОВЫЕ СЕТКИ, ПРОГРАММНАЯ БИБЛИОТЕКА, ОБРАБОТКА ПОЛЬЗОВАТЕЛЬСКОГО ВВОДА, МОДУЛЬНОЕ ТЕСТИРОВАНИЕ. + +Объект практики — программные средства распознавания и исполнения пользовательских символьных команд в интерактивных приложениях. + +Предмет практики — методы и алгоритмы представления графовых сеток, преобразования координатного ввода в дискретный маршрут, сопоставления паттернов и программной организации исполнительного контура библиотеки. + +Целью практики является разработка программной библиотеки для распознавания и исполнения символьных команд, вводимых пользователем на графовых сетках произвольной структуры, обеспечивающей преобразование координат ввода в путь по графовой модели, сопоставление полученного паттерна с зарегистрированной командой и вызов соответствующей логики. + +Результатом работы является реализованное библиотечное ядро GridCasting, включающее графовую модель сетки, механизм локализации пользовательского ввода, исполнительный контур команд, расширяемую подсистему трансформации пути, а также набор автоматизированных тестов, подтверждающих работоспособность основных сценариев обработки. + +## Введение + +Современные интерактивные системы, включая видеоигры и мультимедийные приложения, все чаще используют такие формы взаимодействия, которые позволяют пользователю вводить команды не только через кнопки и меню, но и через более естественные пространственные действия. Одним из таких направлений является работа с графическими паттернами и символьными командами, задаваемыми на плоскости в виде последовательности переходов между опорными точками. Подобные механики представляют практический интерес для игровых и интерактивных приложений, однако их реализация нередко оказывается связанной с ограничениями конкретной геометрии сетки или с жесткой привязкой к заранее заданному формату ввода. + +В рамках данного проекта рассматривается задача распознавания не непрерывного жеста в классическом смысле, а дискретного паттерна, формируемого пользователем на графовой сетке. Такой подход смещает акцент с анализа формы произвольной траектории на интерпретацию последовательности переходов в структуре, заданной графом. Вследствие этого особое значение приобретают абстрактное представление сетки, устойчивость к вариативности пользовательского ввода, а также возможность сопоставления полученного маршрута с набором заранее зарегистрированных команд. + +Целью разработки является создание инструментальной библиотеки, способной преобразовывать координатный ввод пользователя в путь по графовой модели, выполнять подготовку этого пути к сопоставлению и инициировать вызов соответствующей команды. Важным требованием при этом выступает независимость от конкретного типа сетки. Библиотека должна оставаться применимой не только к одной фиксированной геометрии, но и к различным структурам, если они могут быть представлены в виде графа с вершинами и связями между ними. + +Особенность настоящего отчета состоит в том, что он описывает не проектное предположение, а фактически выполненную реализацию. При этом сам документ должен восприниматься как самостоятельный текст, не требующий обращения к проектной части. Поэтому далее кратко повторяются исходные положения задачи, затем рассматриваются изменения, возникшие по мере перехода от проектной модели к коду, после чего последовательно раскрываются использованные средства разработки, реализованные механизмы, программная структура библиотеки, результаты первичной проверки и направления дальнейшего развития. + +## 1. Технологический раздел + +### 1.1. Проектные изменения + +Переход от проектной модели к программной реализации привел не только к подтверждению ранее выбранных архитектурных решений, но и к их уточнению. На этапе проектной практики предполагалось, что библиотека будет состоять из нескольких четко разделенных стадий: интерпретации координат, построения пути, нормализации паттерна, сопоставления с командой и исполнения результата. В текущей реализации эта схема в целом сохранилась, однако конкретное распределение ответственности между компонентами оказалось иным [1.6; 1.7; 1.8]. + +Ниже описываются не абстрактные проектные предположения, а изменения, подтверждаемые текущим состоянием репозитория, листингами кода, тестовым проектом `GridCastingTests` и материалами приложений, включающими структуру каталогов, идентификатор коммита и фрагмент вывода `dotnet test`. + +Первое существенное изменение связано с завершением публичного контура исполнения. В раннем состоянии проекта метод `GridCasting.Execute()` выполнял лишь начальный шаг обработки, передавая координаты в резолвер и не доводя конвейер до исполнения команды. В актуальной реализации это ограничение снято. Класс `GridCasting` теперь создает и хранит экземпляр `PathExecutor`, а публичный метод `Execute(FVector2[] positions)` сначала формирует путь через `GridResolver`, после чего при успешном результате передает его в исполнительный слой. Тем самым библиотека получила завершенную внешнюю точку входа, соответствующую исходному проектному замыслу [1.3; 1.4; 1.5]. + +Второе изменение относится к механизму трансформации паттернов. В проектной документации нормализация рассматривалась как отдельная логическая стадия, близкая по роли к специальному модулю Normalizer. В актуальной реализации эта функция оформлена более гибко: интерфейс `IPathTransform` теперь содержит признак `IsRequired`, а класс `PathExecutor` использует набор трансформаций двояко. При регистрации команды обязательные трансформации применяются к паттерну сразу, а при исполнении исходный путь последовательно расширяется преобразованными вариантами. Если трансформация не обязательна, в пуле кандидатов сохраняется и исходный путь. Такой подход делает архитектуру менее жесткой и лучше приспособленной к сочетанию строгих и альтернативных схем сопоставления [1.1; 1.2; 1.9]. + +Третье изменение связано с расширением ответственности `PathExecutor`. На проектном этапе сопоставление и исполнение мыслились как отдельная стадия после нормализации. В текущем коде исполнительный слой сам хранит ссылку на `GridGraph` и набор трансформов, то есть выступает не только как хранилище команд, но и как управляющий центр для этапа сопоставления. Это изменение можно считать обоснованным: поскольку именно `PathExecutor` принимает окончательное решение о том, какая команда должна быть вызвана, логично, что он же управляет применением трансформаций перед поиском совпадения [1.7; 1.8; 1.10]. + +Четвертое важное уточнение касается графовой модели. Ранее `GridGraph` рассматривался главным образом как абстракция для работы резолвера. В новой реализации появился метод `GridResolver.CreateGridGraph(Grid grid)`, выполняющий обратное преобразование из прикладной сеточной структуры `Grid` в графовую модель. Этот метод не только строит граф, но и валидирует его, отслеживая неоднозначные совпадения и незамкнутые связи. Соответственно, библиотека получила дополнительный технологический уровень: она теперь способна не просто использовать заранее созданный граф, но и восстанавливать его из сеточной структуры при соблюдении условий согласованности [1.6; 1.8]. + +Наконец, были уточнены правила обхода графа и работы с ребрами. В классе `GridGraphEdge` концы ребра сделали изменяемыми внутри сборки, что позволило поэтапно достраивать граф при преобразовании из `Grid`. Одновременно в `GridResolver` была пересмотрена логика прохождения ребер: длина перехода теперь трактуется со знаком в зависимости от того, из какого конца ребра выполняется движение. Это исправление имеет не только техническое, но и содержательное значение, поскольку делает обход двусторонней графовой структуры корректным и согласованным с геометрией узлов [1.6; 1.7]. + +Таким образом, изменения относительно проектной практики носят не декларативный, а конструктивный характер. Они не отменяют исходную архитектурную идею, а переводят ее в более реализуемую и более гибкую форму. При этом важно подчеркнуть, что ряд проектных положений уже достигнут практически, тогда как некоторые - прежде всего углубленная нормализация паттернов и развитый тестовый контур - пока продолжают оставаться задачами следующего этапа [1.1; 1.2; 1.8]. + +### Сопоставление проектной и актуальной архитектурных схем + +Для технологического отчета важно показать не только перечень изменений, но и их архитектурное выражение. Поэтому целесообразно сопоставить исходную структурную схему из проектной части и обновленную схему, соответствующую фактической реализации библиотеки. Такое сравнение позволяет увидеть, какие идеи сохранились, а какие были конкретизированы или перераспределены между новыми программными компонентами [1.7; 1.8; 1.10]. + +Ниже приведена диаграмма, перенесенная из `project.md` без смысловых изменений. Она отражает то представление о системе, которое использовалось на проектном этапе. + +```plantuml +--- +title: Структурная схема из проектной части +--- +@startuml "Структурная схема из проектной части" + +package "Ввод" { + [UserInput] +} + +package "Обработка" { + [Grid] + [DirectionEncoder] + [PathBuilder] + [Normalizer] + [Matcher] +} + +package "Хранилище" { + [CommandRepository] +} + +package "Исполнение" { + [ActionExecutor] +} + +UserInput --> Grid +Grid --> DirectionEncoder +DirectionEncoder --> PathBuilder +PathBuilder --> Normalizer +Normalizer --> Matcher +Matcher --> CommandRepository +Matcher --> ActionExecutor + +@enduml +``` + +Актуальная реализация может быть представлена следующей схемой, в которой показаны уже не проектные роли, а конкретные классы и интерфейсы текущего кода. + +```plantuml +--- +title: Актуальная структурная схема реализации GridCasting +--- +@startuml "Актуальная структурная схема реализации GridCasting" + +package "Внешний вызов" { + [UserInput] + [GridCasting] +} + +package "Преобразование ввода" { + [GridResolver] + [PointBVH2D] + [GridGraph] + [Grid] +} + +package "Сопоставление паттернов" { + [IPathTransform] + [PathExecutor] + [Trie] +} + +package "Исполнение" { + [ICommand] + [CommandContext] + [IEnvironmentResolver] +} + +UserInput --> GridCasting +GridCasting --> GridResolver +GridResolver --> PointBVH2D +GridResolver --> GridGraph +Grid --> GridResolver +GridCasting --> PathExecutor +PathExecutor --> IPathTransform +PathExecutor --> Trie +Trie --> ICommand +PathExecutor --> CommandContext +CommandContext --> IEnvironmentResolver + +@enduml +``` + +Сопоставление этих схем показывает, что проектная цепочка `DirectionEncoder -> PathBuilder -> Normalizer -> Matcher` не исчезла, а была уплотнена и перераспределена. В фактической реализации преобразование координат в маршрут сосредоточено в `GridResolver`, тогда как функции нормализации и сопоставления паттернов перенесены в связку `IPathTransform` и `PathExecutor`. Таким образом, новая архитектура сохраняет логику исходного замысла, но выражает ее через меньшее число более емких компонентов [1.1; 1.2; 1.6]. + +Существенно изменился и способ представления хранилища и исполнения команд. Вместо абстрактных блоков `CommandRepository` и `ActionExecutor` в коде используются конкретные средства: `Trie` как структура хранения паттернов, `PathExecutor` как управляющий центр сопоставления и вызов `ICommand.Execute(...)` через `CommandContext` как форма исполнения результата. За счет этого новая диаграмма отражает не просто теоретический сценарий работы, а реальную внутреннюю организацию библиотеки [1.8; 1.10]. + +Отдельно следует отметить появление элементов, отсутствовавших в проектной диаграмме в явном виде. К ним относятся фасад `GridCasting`, пространственный индекс `PointBVH2D`, а также обратное преобразование `Grid -> GridGraph`, ставшее возможным благодаря `GridResolver.CreateGridGraph`. Эти компоненты показывают, что за время технологической практики библиотека приобрела более завершенный программный контур и стала ближе к практической интеграции в интерактивные приложения [1.3; 1.4; 1.5; 1.9]. + +### 1.2. Обоснование выбора средств разработки проекта в целом + +Выбор технологической платформы определялся особенностями разрабатываемой библиотеки. Проект связан с обработкой структурированных данных, геометрическими вычислениями, обходом графовых моделей и построением расширяемого программного интерфейса. Для таких задач требовалась среда, которая одновременно поддерживает строгую типизацию, обеспечивает достаточно высокую производительность и позволяет без избыточных затрат встраивать результат в другие приложения. Поэтому в качестве основного языка реализации был выбран C#, а в качестве платформы - .NET 8 [2.1; 2.2]. + +Использование C# оправдано прежде всего архитектурно. Проект состоит из нескольких взаимосвязанных слоев: модели графовой сетки, подсистемы разрешения пользовательского ввода, исполнительного слоя команд и набора утилит для пространственного поиска и хранения паттернов. В такой системе строгая типизация является не только средством контроля ошибок, но и формой проектирования интерфейсов. Это особенно заметно в конструкциях `ICommand`, `IEnvironmentResolver` и `IPathTransform`, которые задают точки расширения библиотеки. Поддержка nullable-типов также повышает надежность кода за счет более явного контроля ссылочных состояний [2.2; 2.3]. + +Платформа .NET 8 была выбрана как поддерживаемая LTS-среда исполнения, сочетающая кроссплатформенность и производительность, достаточную для интерактивной обработки пользовательского ввода. Важно, что библиотека не привязана к одному конкретному движку или типу приложения. Благодаря этому .NET позволяет сохранить изначально задуманную универсальность решения. Дополнительным преимуществом является стандартная система сборки SDK-style и MSBuild, делающая проект удобным для дальнейшего сопровождения, интеграции и публикации [2.1; 2.4; 2.5]. + +Отдельно следует отметить подключение внешнего математического модуля `IgdrasilMath`. Для рассматриваемой библиотеки операции над двумерными векторами, расстояниями и ограничивающими прямоугольниками являются базовыми. Использование уже существующего математического компонента позволило не дублировать низкоуровневую геометрическую инфраструктуру и сосредоточиться на ключевой задаче проекта - распознавании графовых паттернов и исполнении связанных с ними команд. + +### 1.3. Обоснование выбора инструментальных средств для отдельных элементов + +Основой библиотеки выступает графовая модель сетки, представленная классами `GridGraph`, `GridGraphNode` и `GridGraphEdge`. Выбор именно графового представления является принципиальным, поскольку позволяет отделить топологию связей между узлами от конкретного типа замощения. В рамках поставленной задачи это важнее, чем удобство работы с какой-либо одной конкретной сеткой, потому что библиотека должна оставаться применимой в различных интерактивных средах. Дополнение ребра параметрами угла и длины позволяет объединить топологическую и геометрическую сторону модели в одной структуре [2.8; 2.9; 2.10; 2.11]. + +Роль центрального вычислительного инструмента выполняет `GridResolver`. Он объединяет в себе несколько функций, которые в проектной модели могли бы быть распределены между отдельными модулями: проверку графа, генерацию сеточного представления, локализацию координат, построение маршрута и восстановление графа из `Grid`. Такое объединение оправдано практикой реализации: все перечисленные задачи используют одну и ту же графовую основу и один набор геометрических допущений, поэтому их сосредоточение в общем компоненте упрощает взаимодействие модулей и делает логику преобразований более согласованной [2.8; 2.9]. + +Для пространственного поиска выбран `PointBVH2D`. Его использование объясняется тем, что сопоставление пользовательской координаты с вершиной графа не должно строиться на полном переборе всех точек. По мере роста графа это привело бы к избыточным затратам. BVH-индекс, напротив, позволяет ограничить проверку лишь релевантными областями пространства и тем самым ускорить локализацию ввода. В контексте библиотеки этот выбор особенно уместен, поскольку поиск ближайшей точки является частью более общего контура распознавания паттерна [2.8; 2.10; 2.11]. + +Для хранения командных паттернов используется префиксное дерево `Trie`. Такой выбор соответствует самой форме данных: путь в библиотеке представляет собой последовательность целых чисел, включающую стартовый узел и набор локальных переходов. Префиксное дерево естественно поддерживает хранение и сопоставление таких последовательностей, а также оставляет пространство для дальнейшего расширения, связанного с семействами паттернов и альтернативными вариантами распознавания [2.8; 2.9; 2.10]. + +Инструментальным средством для управления преобразованиями пути служит интерфейс `IPathTransform`. В актуальной версии проекта он не просто задает операции преобразования и обратного преобразования, но и позволяет делить трансформации на обязательные и факультативные. Это делает механизм сопоставления более гибким и переводит нормализацию из жестко фиксированного этапа в управляемый набор правил, который может расширяться без изменения ядра библиотеки [2.2; 2.3]. + +Принципиальная роль данного интерфейса видна уже на уровне его определения, где явно зафиксировано различие между обязательными и необязательными преобразованиями. + +```csharp +public interface IPathTransform +{ + public bool IsRequired { get; } + public Path Transform(GridGraph graph, Path path); + public Path Reverse(GridGraph graph, Path path); +} +``` + +Исполнительный контур строится вокруг `PathExecutor`, `CommandContext`, `ICommand`, `IEnvironmentResolver` и `ListenableDictionary`. Такой набор выбран потому, что он отделяет задачу распознавания команды от задачи управления состоянием внешней среды. Команда в данной архитектуре рассматривается не как жестко прошитая функция, а как объект, получающий контекст и работающий с состоянием через согласованный интерфейс. Это особенно важно для будущего использования библиотеки в игровых и интерактивных системах, где сам факт распознавания паттерна еще не является конечной целью [2.2; 2.3; 2.11]. + +### 1.4. Описание реализации практических процессов библиотеки + +Реализация практических процессов в GridCasting может быть представлена как последовательность технологических стадий, проходящих от исходной сеточной модели и пользовательского ввода к исполнению команды. Первой такой стадией является построение или использование графовой структуры. Если граф задан напрямую, библиотека может немедленно использовать его для локализации и обхода. Если же исходная структура представлена в виде `Grid`, то `GridResolver.CreateGridGraph` позволяет преобразовать ее в графовую модель, одновременно проверяя целостность связей и отсутствие неоднозначностей. + +После подготовки графа выполняется инициализация `GridResolver`, в ходе которой граф обходится, для каждой вершины вычисляется координатное представление и формируется пространственный индекс `PointBVH2D`. На этом этапе библиотека фактически строит внутреннюю карту опорных точек, которые в дальнейшем будут сопоставляться с пользовательским вводом. Эта стадия важна тем, что переносит существенную часть вычислительной работы из онлайн-обработки в фазу подготовки. + +Следующий процесс начинается в публичном методе `GridCasting.Execute(FVector2[] positions)`. Полученный массив координат передается в `GridResolver.GetPath`, который сначала определяет стартовую точку, а затем последовательно проверяет возможность перехода по каждому следующему ребру. Если ввод согласован со структурой графа, формируется объект `Path`; если нет, обработка прекращается. Таким образом, непрерывный координатный ввод преобразуется в дискретный маршрут по графу. + +Текущее состояние внешнего контура хорошо видно в реализации фасада `GridCasting`, где распознавание и исполнение уже объединены в одном публичном сценарии. + +```csharp +public class GridCasting( + GridGraph graph, + float sensitivity, + params IEnumerable transforms +) { + private readonly GridResolver _resolver = new(graph, sensitivity); + + public PathExecutor Executor { get; } = new(graph, transforms); + + public void Execute(FVector2[] positions) + { + var path = _resolver.GetPath(positions); + if (path.HasValue) Executor.Execute(path.Value); + } +} +``` + +После построения пути управление передается в `PathExecutor`. На этой стадии проявляется одно из ключевых обновлений текущей реализации. Исполнительный слой не ограничивается простым поиском точного совпадения: он последовательно применяет к пути заданные трансформации. Для обязательных трансформаций дальнейшая обработка ведется только через преобразованный вариант, а для необязательных сохраняются и исходные, и преобразованные пути. Полученное множество кандидатных маршрутов затем используется для поиска команды в trie-структуре. + +Если совпадение найдено, создается `CommandContext`, включающий исходный путь, состояние окружения и стек исполнения. После этого вызывается метод `Execute` соответствующей команды. Следовательно, в актуальной версии проекта реализован уже не только внутренний алгоритм распознавания, но и полноценный внешний цикл исполнения: от координатного ввода до запуска прикладной логики. + +#### Минимальный пример использования библиотеки как внешнего API + +Для читателя важно видеть не только внутреннюю структуру классов, но и то, как библиотека применяется извне. Наиболее показателен пример, в котором задействован полный пайплайн: создается граф, подключается `IEnvironmentResolver`, регистрируется команда, затем в библиотеку передается координатный ввод, а успешное распознавание приводит к изменению внешнего состояния через окружение исполнения. + +```csharp +public sealed class CombatStateResolver : IEnvironmentResolver +{ + private readonly Dictionary _state = new() + { + ["spellReady"] = false + }; + + public IEnumerable> OnLoad() => _state; + public void OnUnload() { } + public object? OnReset(string key) => key == "spellReady" ? false : null; + public void OnChange(string key, object value) => _state[key] = value; + public event Action OnUpdate = delegate { }; +} + +public sealed class PrepareSpellCommand : ICommand +{ + public void Execute(CommandContext context) + { + context.Environment["spellReady"] = true; + } +} + +var graph = new GridGraph(); +var node = new GridGraphNode(); +for (var i = 0; i < 6; i++) + node.Edges.Add(new GridGraphEdge(node, node, MathF.PI * i / 3, 1)); +graph.Nodes.Add(node); + +var resolver = new CombatStateResolver(); +var casting = new GridCasting.GridCasting(graph, 0.1f); +casting.Executor.AddEnvironmentResolver(resolver); +casting.Executor.AddCommand( + new PrepareSpellCommand(), + new Path(0, 0, 2, 1) +); + +casting.Execute([ + new FVector2(0f, 0f), + new FVector2(1f, 0f), + new FVector2(0.5f, 0.866f), + new FVector2(1f, 1.732f) +]); + +// Ожидаемый эффект: +// resolver содержит состояние spellReady == true +``` + +В приведенном сценарии библиотека используется как внешний механизм игровой логики полного цикла. Координаты пользователя сначала преобразуются в маршрут через `GridResolver`, затем передаются в `PathExecutor`, сопоставляются с зарегистрированным паттерном и, при успехе, инициируют выполнение команды. Команда, в свою очередь, не изменяет глобальное состояние напрямую, а работает через `CommandContext.Environment`, связанный с `IEnvironmentResolver`. Это наглядно показывает, что библиотека уже поддерживает не только распознавание паттерна, но и контролируемое воздействие на внешнюю систему. + +### 1.5. Описание реализованных механизмов + +Первым ключевым механизмом является представление сетки как ориентированно-геометрического графа. Хотя сами связи между узлами в графе не имеют отдельного направления в классическом смысле, библиотека интерпретирует движение по ребру с учетом того, из какого конца оно осуществляется. Это особенно важно в текущей реализации, где длина перехода используется со знаком, а значит, одна и та же связь может корректно обслуживать обход в обе стороны. Такой подход делает геометрию графа согласованной с логикой реального перемещения по сетке. + +Вторым механизмом является построение пути в `GridResolver.GetPath`. Метод начинает с поиска ближайшей опорной точки, затем для каждой следующей координаты проверяет достижимость соответствующей позиции через одно из ребер текущего узла. При успехе записывается индекс локального направления, при неудаче обработка немедленно останавливается. Практическая ценность этого механизма состоит в том, что он переводит произвольную геометрическую траекторию в дискретный маршрут, пригодный для дальнейшего сопоставления. + +Соответствующий фрагмент кода показывает, что движение по ребру интерпретируется с учетом стороны, из которой выполняется обход, а ошибка на любом шаге приводит к отказу от построения маршрута. + +```csharp +public Path? GetPath(FVector2[] positions) +{ + if (positions.Length == 0) return null; + var point = GetNearestPoint(positions[0]); + if (point == null) return null; + var directions = new int[positions.Length - 1]; + var node = point.Node; + var position = point.TreePosition; + for (var i = 1; i < positions.Length; i++) + { + var updated = false; + for (var j = 0; j < node.Edges.Count; j++) + { + var edge = node.Edges[j]; + var length = edge.NodeA == node ? edge.Length : -edge.Length; + var newPos = position + new FVector2( + length * MathF.Cos(edge.Angle), + length * MathF.Sin(edge.Angle) + ); + if (FVector2.Distance(positions[i], newPos) > _sensitivity) continue; + updated = true; + directions[i - 1] = j; + position = newPos; + node = edge.NodeA == node ? edge.NodeB : edge.NodeA; + break; + } + if (!updated) return null; + } + return new Path(_graph.IndexOf(node), directions); +} +``` + +Третий механизм реализует пространственную локализацию через BVH. В `GetNearestPoint` сначала выполняется поиск ближайших точек в пределах чувствительности, а затем, если однозначное совпадение отсутствует, применяется приоритетный графовый обход с уточнением положения. Это показывает, что библиотека опирается не на примитивное сопоставление координат с ближайшей вершиной, а на комбинированную стратегию, в которой геометрическая близость и топологическая достижимость работают совместно. + +Четвертый механизм связан с трансформацией паттернов. В текущем состоянии проекта это уже не только архитектурная заготовка, но и реальный участник исполнительного контура. Признак `IsRequired` вводит различие между преобразованиями, обязательными для регистрации и поиска команды, и преобразованиями, создающими альтернативные варианты маршрута. Благодаря этому библиотека получает более гибкую схему нормализации и сравнения паттернов, чем предполагалось в ранней версии текста. + +Пятым механизмом является сопоставление маршрута с командой через `Trie`. Здесь особенно важен тот факт, что регистрация команды и ее исполнение используют единый принцип подготовки паттернов. При добавлении команды обязательные трансформации сразу приводят паттерн к рабочему виду, а при исполнении входной путь преобразуется по тем же правилам. Это обеспечивает согласованность хранения и поиска, что для библиотечного решения принципиально. + +Ниже приведен фрагмент `PathExecutor`, в котором это единство регистрации и исполнения выражено непосредственно. + +```csharp +public void AddCommand(ICommand command, Path pattern, bool patternFamily = false) +{ + pattern = _transforms.Where(transform => transform.IsRequired) + .Aggregate(pattern, (current, transform) => transform.Transform(_graph, current)); + _commands.Set(pattern.ToArray(), patternFamily, command); +} + +public bool Execute(Path path) +{ + var paths = new List([path]); + foreach (var transform in _transforms) + { + var newPaths = paths.Select(p => transform.Transform(_graph, p)).ToList(); + if (!transform.IsRequired) + newPaths.AddRange(paths); + paths = newPaths; + } + foreach (var p in paths) + { + if (!_commands.TryGetValue(p.ToArray(), out var command)) continue; + command.Execute(new CommandContext( + path, + _environmentVariablesListenable, + _stack + )); + return true; + } + return false; +} +``` + +Шестой механизм относится к окружению исполнения. `PathExecutor` хранит словарь переменных окружения, обернутый в `ListenableDictionary`, и связывает его с пользовательскими резолверами. За счет этого исполняемая команда получает доступ не только к распознанному паттерну, но и к изменяемому состоянию внешней системы. Следовательно, библиотека уже на текущем этапе ориентирована на интеграцию в приложение, где распознанная команда должна вызывать содержательное изменение состояния. + +### 1.6. Описание реализованного программного пространства + +В рамках данного проекта корректнее говорить не об игровом пространстве в обычном смысле, а о реализованном программном пространстве библиотеки. Репозиторий не содержит самостоятельной сцены, интерфейса пользователя, визуального редактора паттернов или законченного демонстрационного приложения. Вместо этого в нем сформировано программное пространство, состоящее из связанных модулей, через которые проходит обработка данных. + +Нижний уровень этого пространства образуют модели `Grid`, `GridNode`, `GridGraph`, `GridGraphNode`, `GridGraphEdge` и `Path`. Они задают формальное представление сеточной структуры и маршрута. Следующий уровень образует `GridResolver`, который связывает графовую модель с координатным вводом и поддерживает как прямое построение маршрута, так и обратное преобразование сетки в граф. Еще выше расположен исполнительный слой, включающий `PathExecutor`, трансформы пути, команды и окружение исполнения. + +Для этого уровня важен и обратный технологический шаг, поскольку библиотека умеет не только использовать готовую графовую модель, но и восстанавливать ее из сеточного представления. + +```csharp +public static GridGraph? CreateGridGraph(Grid grid) +{ + if (grid.Nodes.Count == 0) return null; + var graph = new GridGraph(); + var graphNodes = new Dictionary(); + var queue = new Queue<(GridNode? prev, GridNode curr)>(); + queue.Enqueue((null, grid.Nodes[0])); + + while (queue.TryDequeue(out var result)) + { + var (prev, curr) = result; + if (graphNodes.TryGetValue(curr, out var match)) continue; + + foreach (var connection in curr.Connections.OfType()) + queue.Enqueue((curr, connection)); + + // Поиск совместимого узла графа или создание нового + // с последующей проверкой связности и однозначности. + } + + return graphNodes.Values.Distinct() + .Any(value => value.Edges.Any(edge => edge.NodeA == null || edge.NodeB == null)) + ? null + : graph; +} +``` + +Таким образом, программное пространство библиотеки охватывает полный внутренний цикл обработки: от модели сетки и геометрии ее узлов до прикладного вызова команды. Отсутствие визуального слоя не является в данном случае недостатком описания, а отражает реальное состояние проекта: на текущем этапе реализовано именно библиотечное ядро, предназначенное для последующей интеграции в более крупную систему. + +### 1.7. Первичная проверка полученной реализации + +Первичная проверка текущей реализации проводилась не только на уровне анализа исходного кода и локальной сборки, но и через отдельный автоматизированный тестовый проект `GridCastingTests`, подключенный к решению на базе `NUnit`. В проекте используются пакеты `Microsoft.NET.Test.Sdk`, `NUnit`, `NUnit3TestAdapter` и `coverlet.collector`, а запуск выполняется стандартной командой `dotnet test`, что соответствует рекомендуемому для .NET сценарию модульного тестирования [2.6; 2.7]. Наличие самостоятельного набора тестов существенно усиливает достоверность выводов о работоспособности реализованных механизмов, хотя и не означает полной верификации всех возможных сценариев использования библиотеки. + +Проверка выполнялась на рабочем дереве проекта с идентификатором коммита `4034c7ce94f52dc53a467bad015db732bc78c805` в окружении `.NET SDK 8.0.420`. Это позволяет связать сделанные выводы не с абстрактной версией проекта, а с конкретным состоянием репозитория, представленным в приложениях. + +Первый проверочный сценарий касается структурной корректности графовой модели. Для этой цели в `GridResolver` присутствует метод `VerifyGridGraph`, позволяющий убедиться, что одна и та же вершина не получает несовместимых пространственных положений при обходе графа. Дополнительно в актуальной реализации появился метод `CreateGridGraph`, который при построении графа из `Grid` отслеживает неоднозначные совпадения и незавершенные связи. Это означает, что библиотека теперь поддерживает не только использование графа, но и его частичную технологическую валидацию в момент конструирования. + +Второй сценарий связан с построением маршрута из координатного ввода. Метод `GetPath` формирует путь только в том случае, если вся последовательность координат может быть интерпретирована как переходы по допустимым ребрам графа. Такой подход позволяет считать реализованным механизм отбраковки несогласованного ввода: если хотя бы один шаг не подтверждается структурой графа, путь не создается. Эта логика подтверждается тестами `TestWorkingPath`, `TestRippedPath` и `TestEmptyPath`, в которых отдельно проверяются корректное построение маршрута, отказ на разорванной траектории и корректная обработка пустого ввода. + +Третий сценарий относится к работе пространственного индекса и генерации координат сетки. `PointBVH2D` обеспечивает поиск ближайших точек в заданном радиусе, а `GetNearestPoint` дополняет этот поиск обходом по графу и уточнением положения. В совокупности это свидетельствует о работоспособности базового механизма локализации пользовательского ввода. Дополнительную проверку геометрической корректности выполняет тест `TestGrid`, который контролирует, что возвращаемые позиции действительно лежат на ожидаемой сеточной структуре. + +Четвертый сценарий связан с исполнительным контуром. В отличие от прежнего состояния проекта, теперь можно говорить о реализации полного внутреннего конвейера: `GridCasting.Execute()` строит путь и передает его в `PathExecutor`, а исполнительный слой, в свою очередь, применяет трансформации, ищет соответствующую команду и при успехе вызывает ее через `CommandContext`. Работоспособность этого слоя подтверждается тестами `TestNoCommands`, `TestWrongCommand`, `TestCommandExecution` и `TestCommandFamily`, которые проверяют поведение при отсутствии зарегистрированных команд, при несовпадении паттерна, при точном совпадении и при использовании семейства паттернов. + +Пятый сценарий касается трансформаций пути. Появление признака `IsRequired` и новой логики в `PathExecutor` показывает, что библиотека теперь поддерживает не только формальное описание трансформаций, но и их фактическое участие в процедуре сопоставления. Это не означает, что задача нормализации решена полностью, поскольку в репозитории по-прежнему не представлены развернутые специализированные реализации трансформов. Однако сам механизм применения обязательных и необязательных преобразований уже встроен в рабочий конвейер и подготовлен к дальнейшему расширению. + +Отдельно была выполнена команда `dotnet test` для проекта `GridCastingTests`. В текущем окружении запуск завершился успешно: пройдено 8 из 8 тестов, а суммарная длительность составила 136 мс. При этом в процессе сборки были зафиксированы предупреждения в зависимых проектах `IgdrasilEngine`, а также отдельные предупреждения nullable-анализа в `GridResolver.cs` и `GridResolverTests.cs`. Эти сообщения не привели к падению тестового прогона, однако указывают на желательность последующей доработки сопутствующего окружения и типовой безопасности кода. + +Фактические результаты проверки удобно представить в табличной форме. + +| Сценарий | Что проверяет | Входные данные | Ожидаемый результат | Фактический результат | +|---|---|---|---|---| +| `TestWorkingPath` | Корректное построение маршрута | Три координаты, соответствующие допустимому пути на тестовом графе | `GetPath` возвращает путь `[0, 2, 1]` | Тест пройден, путь построен корректно | +| `TestRippedPath` | Отбраковку разорванного ввода | Последовательность координат с недопустимым переходом | `GetPath` возвращает `null` | Тест пройден, путь не создан | +| `TestEmptyPath` | Защиту от пустого ввода | Пустой массив `FVector2[]` | `GetPath` возвращает `null` без исключения | Тест пройден, падения не происходит | +| `TestGrid` | Геометрическую корректность генерации позиций | Диапазон `FBox2` для тестового графа | Все позиции принадлежат ожидаемой сетке | Тест пройден | +| `TestNoCommands` | Поведение при отсутствии команд | Корректный путь без зарегистрированных команд | `Execute` возвращает `false` | Тест пройден | +| `TestWrongCommand` | Отказ при несовпадении паттерна | Путь, не совпадающий с зарегистрированным | `Execute` возвращает `false` | Тест пройден | +| `TestCommandExecution` | Исполнение команды при точном совпадении | Зарегистрированный паттерн и совпадающий путь | `Execute` возвращает `true`, команда получает корректный `CommandContext` | Тест пройден | +| `TestCommandFamily` | Поддержку семейства паттернов | Путь, являющийся продолжением семейства | `Execute` возвращает `true` | Тест пройден | + +Зафиксированные предупреждения не блокируют текущий результат по следующим причинам. Во-первых, основная масса предупреждений относится к зависимым проектам `IgdrasilEngine`, а не к логике `GridCasting`. Во-вторых, локальные предупреждения nullable-анализа в `GridResolver.cs` и `GridResolverTests.cs` не приводят к ошибкам выполнения и не помешали успешному прохождению всех тестов. Следовательно, на данном этапе корректно утверждать не полную безупречность сборки, а работоспособность библиотечного ядра в проверенных сценариях. + +### 1.8. Итоги этапа и задачи следующего этапа + +На текущем этапе результат следует формулировать как работоспособное библиотечное ядро и продвинутый прототип, а не как полностью завершенное решение. Чтобы это было видно явно, целесообразно разделить достигнутый результат на три группы. + +Уже реализовано: + +- графовая модель сетки `GridGraph` и связанные модели данных; +- преобразование координатного ввода в путь через `GridResolver`; +- обратное построение графа из `Grid` через `CreateGridGraph`; +- исполнительный контур `PathExecutor` с хранением паттернов в `Trie`; +- механизм обязательных и необязательных `IPathTransform`; +- контекст исполнения команд и поддержка окружения; +- отдельный тестовый проект `GridCastingTests`. + +Подтверждено тестами: + +- корректное построение допустимого пути; +- отказ на разорванном или пустом вводе; +- геометрическая корректность генерации позиций; +- корректная работа `PathExecutor` при отсутствии команды, при несовпадении, при точном совпадении и при использовании семейства паттернов. + +Остается на следующий этап: + +- разработка законченного набора специализированных трансформаций пути; +- создание демонстрационного пользовательского слоя или интеграционного примера; +- расширение тестового покрытия для более сложных конфигураций графов и трансформов; +- дополнительная работа с предупреждениями nullable-анализа и зависимостями. + +## Вывод + +В данной практике была выполнена существенная часть перехода от проектной модели к работоспособному библиотечному ядру. Текущий результат корректно характеризовать как продвинутый прототип: реализован основной конвейер обработки от координатного ввода до вызова команды, построен исполнительный слой, введен механизм трансформаций пути и оформлен отдельный тестовый проект, подтверждающий работоспособность базовых сценариев. + +Особенно важно, что новые изменения усилили именно те участки системы, которые раньше оставались наиболее уязвимыми с точки зрения отчета. Публичный метод `GridCasting.Execute()` перестал быть заготовкой, исполнительный слой стал работать совместно с трансформациями пути, а `GridResolver` получил возможность строить граф из сеточного представления и валидировать его. Это означает, что проект уже нельзя описывать лишь как набор несвязанных подсистем: на данном этапе он представляет собой согласованное библиотечное ядро с подтвержденными внутренними сценариями работы. + +Одновременно результаты работы следует оценивать объективно. Хотя основной конвейер реализован и уже сопровождается автоматизированными тестами, библиотека все еще не имеет демонстрационного пользовательского слоя и пока не показывает законченного набора специализированных трансформаций паттернов. Поэтому речь идет не о завершенном программном продукте, а о работоспособном библиотечном ядре, которое создает прочную основу для следующего этапа разработки. + +## Приложения + +### Приложение А. Структура каталогов проекта + +```text +GridCasting/ +├── GridCasting/ +│ ├── Docs/ +│ │ └── Reports/ +│ ├── Executor/ +│ ├── Models/ +│ │ ├── Grid/ +│ │ └── GridGraph/ +│ ├── Transform/ +│ └── Utils/ +├── GridCastingTests/ +│ ├── ExecutorTests.cs +│ └── GridResolverTests.cs +└── GridCasting.sln +``` + +### Приложение Б. Версия репозитория и среда проверки + +- Коммит проекта: `4034c7ce94f52dc53a467bad015db732bc78c805` +- Версия .NET SDK: `8.0.420` +- Тестовый проект: `GridCastingTests` +- Команда запуска: `dotnet test GridCastingTests/GridCastingTests.csproj` + +### Приложение В. Фрагмент вывода `dotnet test` + +```text +GridCasting -> ...\GridCasting\bin\Debug\net8.0\GridCasting.dll +GridCastingTests -> ...\GridCastingTests\bin\Debug\net8.0\GridCastingTests.dll + +Тестовый запуск для ...\GridCastingTests.dll (.NETCoreApp,Version=v8.0) +Версия VSTest 17.11.1 (x64) + +Запуск выполнения тестов; подождите... +Общее количество тестовых файлов (1), соответствующих указанному шаблону. + +Пройден! : не пройдено 0, пройдено 8, пропущено 0, всего 8, длительность 136 ms. +``` + +## Источники к главе 1 + +[1.1] Anthony L., Wobbrock J. O. $1 Unistroke Recognizer Extensions // CHI. 2020. + +[1.2] Vatavu R.-D. Improving Gesture Recognition Accuracy // ACM Computing Surveys. 2021. + +[1.3] CurseForge. Hexcasting Mod. URL: https://www.curseforge.com/minecraft/mc-mods/hexcasting (дата обращения: 16.04.2026). + +[1.4] Nintendo. Okami Game Guide. 2006. + +[1.5] Arkane Studios. Arx Fatalis Manual. 2002. + +[1.6] Diestel R. Graph Theory. Springer, 2017. + +[1.7] Schell J. The Art of Game Design. CRC Press, 2019. + +[1.8] Fullerton T. Game Design Workshop. CRC Press, 2020. + +[1.9] Norman D. The Design of Everyday Things. 2013. + +[1.10] Shneiderman B. Designing the User Interface. Pearson, 2018. + +## Источники к главе 2 + +[2.1] Microsoft. .NET documentation. URL: https://learn.microsoft.com/en-us/dotnet/ (дата обращения: 16.04.2026). + +[2.2] Microsoft. C# language documentation. URL: https://learn.microsoft.com/en-us/dotnet/csharp/ (дата обращения: 16.04.2026). + +[2.3] Microsoft. Object-Oriented Programming - C#. URL: https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/tutorials/oop (дата обращения: 16.04.2026). + +[2.4] Microsoft. .NET project SDKs. URL: https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview (дата обращения: 16.04.2026). + +[2.5] Microsoft. Use MSBuild project SDKs. URL: https://learn.microsoft.com/en-us/visualstudio/msbuild/how-to-use-project-sdk (дата обращения: 16.04.2026). + +[2.6] Microsoft. Unit testing C# with NUnit and .NET Core. URL: https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-csharp-with-nunit (дата обращения: 16.04.2026). + +[2.7] NUnit. NUnit Documentation Site. URL: https://docs.nunit.org/ (дата обращения: 16.04.2026). + +[2.8] Goodrich M., Tamassia R. Data Structures and Algorithms. Wiley, 2020. + +[2.9] Cormen T., Leiserson C., Rivest R., Stein C. Introduction to Algorithms. MIT Press, 2022. + +[2.10] Sedgewick R., Wayne K. Algorithms. Addison-Wesley, 2022. + +[2.11] Skiena S. The Algorithm Design Manual. Springer, 1998. diff --git a/GridCasting/Docs/api-reference/index.md b/GridCasting/Docs/api-reference/index.md new file mode 100644 index 0000000..0eed83c --- /dev/null +++ b/GridCasting/Docs/api-reference/index.md @@ -0,0 +1,117 @@ +--- +title: Справочник API +order: 6 +--- + +# Справочник API GridCasting + +## Точка входа + +### GridCasting + +Главный фасад библиотеки. + +```csharp +public class GridCasting( + GridGraph graph, + float sensitivity, + params IEnumerable transforms) +``` + +**Основной метод:** + +```csharp +public void Execute(FVector2[] positions) +``` + +## Преобразование ввода + +### GridResolver + +Класс для построения пути и работы с графовой моделью. + +**Основные методы:** + +- `GetPath(FVector2[] positions)` +- `CreateGridGraph(Grid grid)` +- `VerifyGridGraph(GridGraph graph)` +- `GenerateGrid(FBox2 range)` +- `GetGridPositions(FBox2 range)` + +### IPathTransform + +Интерфейс преобразования маршрутов: + +```csharp +public interface IPathTransform +{ + public bool IsRequired { get; } + public Path Transform(GridGraph graph, Path path); + public Path Reverse(GridGraph graph, Path path); +} +``` + +## Исполнение + +### PathExecutor + +Класс, отвечающий за регистрацию и выполнение команд. + +**Основные методы:** + +- `AddCommand(ICommand command, Path pattern, bool patternFamily = false)` +- `Execute(Path path)` +- `AddEnvironmentResolver(IEnvironmentResolver resolver)` +- `RemoveEnvironmentResolver(IEnvironmentResolver resolver)` +- `ResetStack()` + +### ICommand + +Интерфейс прикладной команды: + +```csharp +public interface ICommand +{ + void Execute(CommandContext context); +} +``` + +### CommandContext + +Контекст, передаваемый в исполняемую команду. + +### IEnvironmentResolver + +Интерфейс интеграции с внешним окружением. + +## Модели данных + +### Path + +Дискретное представление маршрута пользователя. + +### Grid + +Прикладная сеточная структура, состоящая из `GridNode`. + +### GridGraph + +Абстрактный граф сетки, включающий: + +- `GridGraph` +- `GridGraphNode` +- `GridGraphEdge` + +## Вспомогательные структуры + +### Trie + +Префиксная структура хранения паттернов команд. + +### ListenableDictionary + +Словарь с событиями изменения, используемый для окружения исполнения. + +### PointBVH2D + +Пространственный индекс для поиска ближайших точек. diff --git a/GridCasting/Docs/architecture/index.md b/GridCasting/Docs/architecture/index.md new file mode 100644 index 0000000..d64dc3a --- /dev/null +++ b/GridCasting/Docs/architecture/index.md @@ -0,0 +1,101 @@ +--- +title: Архитектура +order: 4 +--- + +# Архитектура GridCasting + +GridCasting построен как библиотечный конвейер, который переводит координатный ввод пользователя в исполнимую команду. + +## Общий процесс + +```text +Ввод координат FVector2[] + ↓ + GridCasting + ↓ + GridResolver + ↓ + PointBVH2D + GridGraph + ↓ + Path + ↓ + IPathTransform* + ↓ + PathExecutor + ↓ + Trie + ↓ + CommandContext + Environment + ↓ + ICommand.Execute() +``` + +## Основные компоненты + +### GridCasting + +Фасад библиотеки. Объединяет построение пути и исполнение. + +```csharp +public class GridCasting( + GridGraph graph, + float sensitivity, + params IEnumerable transforms) +``` + +### GridResolver + +Центральный компонент преобразования геометрического ввода в дискретный маршрут. + +Основные задачи: + +- построение `Path` из координат +- восстановление `GridGraph` из `Grid` +- генерация сетки и получение позиций +- валидация структурной корректности графа + +### GridGraph + +Абстрактная модель сетки: + +- `GridGraph` — контейнер узлов +- `GridGraphNode` — вершина +- `GridGraphEdge` — ребро с углом и длиной + +### PointBVH2D + +Пространственный индекс для быстрого поиска ближайших точек графа. Используется `GridResolver` при локализации пользовательского ввода. + +### IPathTransform + +Точка расширения для преобразований маршрута. Трансформы могут быть обязательными и необязательными. + +### PathExecutor + +Исполнительный слой библиотеки: + +- хранит команды в `Trie` +- применяет трансформации +- управляет окружением исполнения +- вызывает нужную команду через `CommandContext` + +## Архитектурные особенности + +### Единый фасад + +Вместо раздельного публичного API для резолвинга и исполнения библиотека предоставляет один понятный вход через `GridCasting`. + +### Разделение топологии и исполнения + +Модель графа и механизм исполнения команд не смешиваются напрямую. Это упрощает расширение библиотеки и повторное использование графовых структур. + +### Контекст исполнения + +Команда получает не только путь, но и доступ к окружению и стеку, что делает библиотеку пригодной для интеграции в более сложные игровые или интерактивные системы. + +## Связанные разделы + +- [Справочник API](../api-reference/) +- [Конфигурация](../configuration/) +- [Отчеты](../Reports/tech_updated.md) diff --git a/GridCasting/Docs/configuration/index.md b/GridCasting/Docs/configuration/index.md new file mode 100644 index 0000000..3bd6c6d --- /dev/null +++ b/GridCasting/Docs/configuration/index.md @@ -0,0 +1,75 @@ +--- +title: Конфигурация +order: 2 +--- + +# Конфигурация проекта GridCasting + +В отличие от приложений с пользовательским интерфейсом, GridCasting не требует отдельного конфигурационного файла для запуска. Основная конфигурация проекта задается на уровне решения, `.csproj` файлов и структуры зависимостей. + +## Основной проект + +Файл: `GridCasting/GridCasting.csproj` + +```xml + + + net8.0 + enable + enable + preview + + +``` + +## Зависимости + +Главная внешняя зависимость библиотеки: + +- `IgdrasilMath` — математические типы и операции (`FVector2`, `FBox2` и др.) + +Подключение задается через `ProjectReference`: + +```xml + + + +``` + +## Тестовый проект + +Файл: `GridCastingTests/GridCastingTests.csproj` + +Используемые пакеты: + +- `Microsoft.NET.Test.Sdk` +- `NUnit` +- `NUnit3TestAdapter` +- `coverlet.collector` + +## Конфигурация на уровне кода + +Основные параметры работы библиотеки задаются программно: + +- `GridGraph graph` +- `float sensitivity` +- `IEnumerable transforms` + +Пример: + +```csharp +var casting = new GridCasting.GridCasting(graph, 0.1f, transforms); +``` + +## Структура документации + +В папке `Docs` сосуществуют: + +- инженерная документация по библиотеке +- папка `Reports` с отчетами по практике + +## Ограничения текущей конфигурации + +- нет отдельного демонстрационного приложения +- конкретные реализации `IPathTransform` пока не выделены в самостоятельный набор +- часть решения зависит от соседних проектов `IgdrasilEngine` diff --git a/GridCasting/Docs/faq/index.md b/GridCasting/Docs/faq/index.md new file mode 100644 index 0000000..046dfa7 --- /dev/null +++ b/GridCasting/Docs/faq/index.md @@ -0,0 +1,46 @@ +--- +title: FAQ +order: 5 +--- + +# Часто задаваемые вопросы + +## Это игровой движок? + +Нет. GridCasting — не полноценный игровой движок и не пользовательское приложение. Это библиотечное ядро, которое можно встроить в игру или интерактивную систему. + +## Поддерживается только шестиугольная сетка? + +Нет. В тестах часто используется простой шестиугольный пример, но сама библиотека построена вокруг `GridGraph` и не ограничена одной геометрией. + +## Есть ли готовый UI? + +Нет. В текущем состоянии проекта визуальный интерфейс, редактор паттернов и демонстрационное приложение отсутствуют. + +## Что делает `sensitivity`? + +Этот параметр задает допустимое отклонение координаты пользователя от ожидаемой графовой точки или позиции перехода. + +## Можно ли добавлять собственные правила нормализации? + +Да. Для этого предназначен интерфейс `IPathTransform`. + +## Как хранятся команды? + +Команды регистрируются через `PathExecutor` и сохраняются во внутренней `Trie`. + +## Есть ли тесты? + +Да. В решении присутствует проект `GridCastingTests`, в котором проверяются сценарии для `GridResolver` и `PathExecutor`. + +## Что пока не завершено? + +На текущем этапе остаются открытыми задачи: + +- расширения набора конкретных трансформов +- создания демонстрационного приложения +- дальнейшего расширения тестового покрытия + +## Где лежат учебные отчеты? + +В папке [Reports](../Reports/tech_updated.md). diff --git a/GridCasting/Docs/getting-started/index.md b/GridCasting/Docs/getting-started/index.md new file mode 100644 index 0000000..12fccf9 --- /dev/null +++ b/GridCasting/Docs/getting-started/index.md @@ -0,0 +1,77 @@ +--- +title: Начало работы +order: -10 +--- + +# Начало работы с GridCasting + +## Требования + +Для работы с проектом требуется: + +- .NET 8 SDK +- доступ к зависимому проекту `IgdrasilMath` +- решение `GridCasting.sln`, если нужно запускать тесты и работать со всей структурой проекта + +## Сборка проекта + +```bash +dotnet build D:\Projects\CSharpProjects\GridCasting\GridCasting.sln +``` + +Если требуется проверить библиотеку автоматизированно: + +```bash +dotnet test D:\Projects\CSharpProjects\GridCasting\GridCastingTests\GridCastingTests.csproj +``` + +## Минимальный сценарий использования + +Ниже приведен упрощенный пример создания графа, регистрации команды и вызова фасада `GridCasting`. + +```csharp +var graph = new GridGraph(); +var node = new GridGraphNode(); +for (var i = 0; i < 6; i++) + node.Edges.Add(new GridGraphEdge(node, node, MathF.PI * i / 3, 1)); +graph.Nodes.Add(node); + +var casting = new GridCasting.GridCasting(graph, 0.1f); +casting.Executor.AddCommand(new DemoCommand(), new Path(0, 1, 1, 2)); +casting.Execute(points); +``` + +## Базовый конвейер + +Работа библиотеки строится по следующей схеме: + +1. Пользователь передает массив координат `FVector2[]`. +2. `GridCasting` вызывает `GridResolver.GetPath(...)`. +3. `GridResolver` определяет ближайшую графовую точку и строит дискретный путь. +4. `PathExecutor` применяет трансформации и ищет совпадение в `Trie`. +5. При совпадении вызывается `ICommand.Execute(...)`. + +## Структура проекта + +```text +GridCasting/ +├── GridCasting/ # Основная библиотека +├── GridCastingTests/ # NUnit тесты +└── GridCasting.sln # Решение +``` + +Внутри библиотеки основные папки: + +```text +GridCasting/ +├── Executor/ +├── Models/ +├── Transform/ +└── Utils/ +``` + +## Что читать дальше + +- [Архитектура](../architecture/) — если нужен обзор внутреннего конвейера +- [Справочник API](../api-reference/) — если нужны основные типы и точки расширения +- [Конфигурация](../configuration/) — если нужна структура решения и зависимости diff --git a/GridCasting/Docs/index.md b/GridCasting/Docs/index.md index e69de29..f7fc60c 100644 --- a/GridCasting/Docs/index.md +++ b/GridCasting/Docs/index.md @@ -0,0 +1,120 @@ +--- +title: GridCasting - Библиотека распознавания символьных команд +order: 0 +--- + +**GridCasting** — это библиотека на C#/.NET для распознавания и исполнения символьных команд, вводимых пользователем на графовых сетках произвольной структуры. Она преобразует координатный ввод в дискретный путь по графу, применяет трансформации паттерна, сопоставляет результат с зарегистрированными командами и запускает связанную логику исполнения. + +## Что умеет GridCasting? + +✅ Работать с произвольной графовой моделью сетки +✅ Преобразовывать координаты ввода в путь по графу +✅ Использовать пространственный индекс для локализации точек +✅ Хранить команды в префиксной структуре `Trie` +✅ Поддерживать обязательные и необязательные трансформации пути +✅ Передавать в команду контекст исполнения и окружение +✅ Проверяться через отдельный тестовый проект `GridCastingTests` + +## Быстрый старт + +```csharp +using GridCasting; +using GridCasting.Executor; +using GridCasting.Models.GridGraph; +using IgdrasilEngine.Engine.Math.Vectors; + +var graph = new GridGraph(); +var node = new GridGraphNode(); +for (var i = 0; i < 6; i++) + node.Edges.Add(new GridGraphEdge(node, node, MathF.PI * i / 3, 1)); +graph.Nodes.Add(node); + +var casting = new GridCasting.GridCasting(graph, 0.1f); +casting.Executor.AddCommand(new MyCommand(), new Models.Path(0, 1, 1, 2)); + +casting.Execute([ + new FVector2(0, 0), + new FVector2(1, 0), + new FVector2(1.5f, 0.866f), + new FVector2(0.5f, 0.866f) +]); +``` + +## Структура документации + +Папки в `Docs/` образуют разделы документации: + +``` +Docs/ +├── index.md +├── getting-started/ +├── architecture/ +├── configuration/ +├── api-reference/ +├── faq/ +├── writing-docs/ +└── Reports/ +``` + +## Основные разделы + +### [Начало работы](./getting-started/) + +Сборка проекта, подключение библиотеки и первый сценарий использования. + +### [Архитектура](./architecture/) + +Описание конвейера обработки от координатного ввода до исполнения команды. + +### [Конфигурация](./configuration/) + +Сведения о проектах решения, зависимостях, тестах и структуре папок. + +### [Справочник API](./api-reference/) + +Ключевые классы, интерфейсы и модели данных библиотеки. + +### [Часто задаваемые вопросы](./faq/) + +Краткие ответы на вопросы по интеграции и ограничениям текущей реализации. + +### [Отчеты](./Reports/project.md) + +Проектная и технологическая документация, подготовленная в рамках практики. + +## Ключевые идеи + +### Граф как базовая модель + +GridCasting не зависит от одной конкретной геометрии сетки. В основе лежит `GridGraph`, описывающий вершины и связи между ними. + +### Путь как дискретный паттерн + +Пользовательский ввод интерпретируется не как непрерывный жест, а как последовательность переходов между узлами графа. + +### Исполнение через контекст + +Команда вызывается не напрямую, а через `CommandContext`, содержащий путь, окружение и стек исполнения. + +## Рекомендуемый порядок чтения + +1. [Начало работы](./getting-started/) — как собрать и использовать библиотеку +2. [Архитектура](./architecture/) — как устроен внутренний конвейер +3. [Справочник API](./api-reference/) — какие типы составляют ядро +4. [Конфигурация](./configuration/) — как устроен проект и решение +5. [Часто задаваемые вопросы](./faq/) — ограничения и типовые вопросы +6. [Отчеты](./Reports/tech_updated.md) — исследовательская и отчетная часть проекта + +## Дополнительно + +- **Тесты:** проект `GridCastingTests` содержит автоматизированные проверки для `GridResolver` и `PathExecutor` +- **Зависимость:** библиотека использует `IgdrasilMath` для векторной и геометрической обработки +- **Платформа:** .NET 8.0 +- **Язык:** C# + +--- + +**Проект:** GridCasting +**Назначение:** библиотечное ядро для интерактивных и игровых систем +**Язык:** C# / .NET 8 +**Связанные материалы:** [Reports](./Reports/tech_updated/) diff --git a/GridCasting/Docs/license.md b/GridCasting/Docs/license.md new file mode 100644 index 0000000..576ede1 --- /dev/null +++ b/GridCasting/Docs/license.md @@ -0,0 +1,28 @@ +--- +title: Лицензия +description: No License +order: 100 +layout: license +--- + +# Лицензия + +В текущем репозитории для GridCasting не оформлена отдельная текстовая лицензия в составе `Docs`. + +На практике это означает следующее: + +- условия распространения и использования следует определять по правилам основного репозитория +- при внешней публикации документации стоит добавить отдельный файл лицензии +- если библиотека будет выделяться в самостоятельный продукт, раздел лицензирования желательно оформить явно + +## Рекомендация + +При следующем этапе развития проекта имеет смысл: + +1. выбрать лицензионную модель; +2. добавить файл `LICENSE` в корень репозитория; +3. синхронизировать этот раздел документации с выбранной лицензией. + +
+© 2026 Alexander Izmailov. +
\ No newline at end of file diff --git a/GridCasting/Docs/writing-docs/index.md b/GridCasting/Docs/writing-docs/index.md new file mode 100644 index 0000000..5b833b6 --- /dev/null +++ b/GridCasting/Docs/writing-docs/index.md @@ -0,0 +1,58 @@ +--- +title: Написание документации +order: 3 +--- + +# Как поддерживать документацию GridCasting + +Документация проекта разделена на два уровня: + +- инженерная документация по библиотеке в `Docs/` +- учебные и исследовательские отчеты в `Docs/Reports/` + +## Общие правила + +### 1. Главная страница раздела + +Каждая папка раздела должна содержать `index.md`. + +### 2. YAML frontmatter + +Для всех страниц желательно указывать: + +```markdown +--- +title: Название страницы +order: 0 +--- +``` + +### 3. Содержательность + +Документация к библиотеке должна отвечать на практические вопросы: + +- что делает компонент +- как он используется +- с какими типами связан +- какие ограничения имеет + +## Что документировать в первую очередь + +Особенно важно поддерживать в актуальном состоянии описание: + +- `GridCasting` +- `GridResolver` +- `PathExecutor` +- `IPathTransform` +- `ICommand` +- `IEnvironmentResolver` + +## Как оформлять отчеты + +Отчеты практики лучше хранить отдельно от прикладной документации, поэтому для них выделена папка `Reports`. + +Рекомендуемый подход: + +- инженерные страницы не перегружать учебными формулировками +- отчеты не смешивать с API-справочником +- в главной документации давать только ссылки на отчеты diff --git a/GridCasting/Executor/CommandContext.cs b/GridCasting/Executor/CommandContext.cs index 86d0f8a..210b92c 100644 --- a/GridCasting/Executor/CommandContext.cs +++ b/GridCasting/Executor/CommandContext.cs @@ -2,12 +2,38 @@ namespace GridCasting.Executor; +/// +/// Represents the context in which a command is executed. +/// This class encapsulates the command, the execution environment, and a stack for managing execution state. +/// public class CommandContext { + /// + /// Represents the primary command property for execution within a given context. + /// This property encapsulates a path structure defined by a start node and a series of directions. + /// public Path Command { get; } + + /// + /// Represents the execution environment for the command context. + /// This property provides a dictionary for storing key-value pairs that define the state, configuration, or resources + /// necessary for command execution within the current context. + /// public IDictionary Environment { get; } + + /// + /// Represents a stack used for managing execution state within the command context. + /// This property provides a mechanism to maintain a dynamic collection of objects required during command execution. + /// public Stack Stack { get; } - + + /// + /// Represents the context in which a command is executed. + /// + /// + /// Encapsulates information required for the execution of a command, including + /// the command itself, the execution environment, and the associated execution stack. + /// internal CommandContext(Path command, IDictionary environment, Stack stack) { Command = command; diff --git a/GridCasting/Executor/ICommand.cs b/GridCasting/Executor/ICommand.cs index eeb395f..b9379ee 100644 --- a/GridCasting/Executor/ICommand.cs +++ b/GridCasting/Executor/ICommand.cs @@ -1,8 +1,15 @@ -using Path = GridCasting.Models.Path; - -namespace GridCasting.Executor; +namespace GridCasting.Executor; +/// +/// Represents an executable command that can be invoked with a specific execution context. +/// This interface defines a contract for implementing custom commands in the application. +/// public interface ICommand { + /// + /// Executes a command within the provided execution context. + /// This method defines the operational logic for the command, utilizing the given context for execution. + /// + /// The execution context that contains the specific environment, stack, and command information required for executing this command. void Execute(CommandContext context); } \ No newline at end of file diff --git a/GridCasting/Executor/IEnvironmentResolver.cs b/GridCasting/Executor/IEnvironmentResolver.cs index 0d5cc8b..196def5 100644 --- a/GridCasting/Executor/IEnvironmentResolver.cs +++ b/GridCasting/Executor/IEnvironmentResolver.cs @@ -1,5 +1,9 @@ namespace GridCasting.Executor; +/// +/// Provides an abstraction for managing and resolving environment-specific variables, +/// enabling the dynamic loading, updating, resetting, and unloading of environment configurations. +/// public interface IEnvironmentResolver { /// diff --git a/GridCasting/Executor/PathExecutor.cs b/GridCasting/Executor/PathExecutor.cs index c2c10b8..76ec4a3 100644 --- a/GridCasting/Executor/PathExecutor.cs +++ b/GridCasting/Executor/PathExecutor.cs @@ -1,4 +1,6 @@ -using GridCasting.Utils; +using GridCasting.Models.GridGraph; +using GridCasting.Transform; +using GridCasting.Utils; using Path = GridCasting.Models.Path; namespace GridCasting.Executor; @@ -16,6 +18,31 @@ namespace GridCasting.Executor; /// public class PathExecutor { + /// + /// Represents the graph structure used for path execution in the class. + /// This field stores the instance of , which contains the nodes and relationships + /// that define the underlying grid configuration. + /// + /// + /// The field acts as a foundational data structure for path-related operations. + /// It is used to manage, traverse, and interact with grid nodes during the execution of commands or + /// transformations. The graph consists of a collection of instances + /// which can be iterated or accessed by index. + /// + private readonly GridGraph _graph; + + /// + /// Holds a collection of path transformation implementations that are applied during path execution. + /// Each transformation conforms to the interface, enabling dynamic + /// modification of paths based on specific rules or a grid graph structure. + /// + /// + /// The field is populated with a set of provided path transform instances. These transform instances + /// are used to modify or adapt path-related data during the execution process, and ensure a flexible + /// mechanism for interacting with different graph configurations or path scenarios. + /// + private readonly IEnumerable _transforms; + /// /// Stores the internal mapping of commands to their corresponding path patterns. /// This data structure associates commands, which implement the interface, @@ -89,8 +116,10 @@ public class PathExecutor /// removals, or full-clears of its contents. It acts as a mediator for resolving context and executing commands /// based on the given path patterns. /// - public PathExecutor() + public PathExecutor(GridGraph graph, params IEnumerable transforms) { + _graph = graph; + _transforms = transforms; _environmentVariablesListenable = new ListenableDictionary(_environmentVariables); _environmentVariablesListenable.OnUpdate += OnUpdate; _environmentVariablesListenable.OnRemove += OnRemove; @@ -132,7 +161,7 @@ public class PathExecutor /// /// The environment resolver to be removed. It will be unregistered /// from its update events, and its context will be cleaned up. - public void RemoveContextResolver(IEnvironmentResolver resolver) + public void RemoveEnvironmentResolver(IEnvironmentResolver resolver) { // Unmap all environment variables resolver.OnUpdate -= OnResolverUpdate; @@ -146,13 +175,17 @@ public class PathExecutor } /// - /// Adds a command to be executed with an associated path pattern and optional pattern family configuration. + /// Adds a command associated with a specific path pattern and optionally its family to the internal command collection. /// - /// The command to add. Must implement the interface. - /// The path object used to define the execution pattern for the command. - /// A boolean flag indicating whether the path pattern should be treated as a family of patterns. Defaults to false. - public void AddCommand(ICommand command, Path pattern, bool patternFamily = false) => + /// The command to be executed when the associated pattern is matched. + /// The discrete path pattern which identifies the context for the command. + /// Indicates whether the command should apply to the entire pattern family (optional, default is false). + public void AddCommand(ICommand command, Path pattern, bool patternFamily = false) + { + pattern = _transforms.Where(transform => transform.IsRequired) + .Aggregate(pattern, (current, transform) => transform.Transform(_graph, current)); _commands.Set(pattern.ToArray(), patternFamily, command); + } /// @@ -161,24 +194,37 @@ public class PathExecutor /// public void ResetStack() => _stack.Clear(); + /// - /// Executes the command associated with the provided path. - /// If a matching command is found, it is executed within the provided execution context. + /// Executes a command associated with the given path, applying all specified path transformations + /// and resolving the appropriate command to execute based on the transformed paths. /// - /// The path object defining the start node and directions for the execution. + /// The initial path to be transformed and evaluated for command execution. /// - /// Returns true if a matching command for the specified path is found and executed successfully; - /// otherwise, returns false. + /// A boolean value indicating whether a command was successfully executed for the given path. + /// Returns true if a command was executed; otherwise, false. /// public bool Execute(Path path) { - if (!_commands.TryGetValue(path.ToArray(), out var command)) return false; - command.Execute(new CommandContext( - path, - _environmentVariablesListenable, - _stack - )); - return true; + var paths = new List([path]); + foreach (var transform in _transforms) + { + var newPaths = paths.Select(p => transform.Transform(_graph, p)).ToList(); + if (!transform.IsRequired) + newPaths.AddRange(paths); + paths = newPaths; + } + foreach (var p in paths) + { + if (!_commands.TryGetValue(p.ToArray(), out var command)) continue; + command.Execute(new CommandContext( + path, + _environmentVariablesListenable, + _stack + )); + return true; + } + return false; } /// diff --git a/GridCasting/GridCasting.cs b/GridCasting/GridCasting.cs index e763b44..47e05dd 100644 --- a/GridCasting/GridCasting.cs +++ b/GridCasting/GridCasting.cs @@ -2,22 +2,48 @@ using GridCasting.Models.GridGraph; using GridCasting.Transform; using IgdrasilEngine.Engine.Math.Vectors; +using Path = GridCasting.Models.Path; namespace GridCasting; +/// +/// Represents the main class for performing grid-based operations +/// with casting mechanisms. This class integrates a path executor +/// with a grid graph and allows operations based on positional data +/// provided by the user. +/// public class GridCasting( - PathExecutor executor, - GridGraph graph, - float sensitivity, - params IEnumerable transforms) -{ + GridGraph graph, + float sensitivity, + params IEnumerable transforms +) { + /// + /// A private, read-only instance of the class that is responsible + /// for resolving grid-based operations such as determining paths, generating grids, + /// and acquiring positional information. It operates on the provided + /// and uses a specified sensitivity value for fine-tuning resolution behavior. + /// private readonly GridResolver _resolver = new(graph, sensitivity); - private readonly PathExecutor _executor = executor; - private readonly IEnumerable _transforms = transforms; + /// + /// Gets an instance of the class, responsible for executing + /// pathfinding and grid-based operations. The executor interacts with the underlying + /// and applies transformations using the specified + /// instances to modify or adapt the path resolution process. + /// + public PathExecutor Executor { get; } = new(graph, transforms); + + /// + /// Executes an operation by resolving a path from the given positions + /// and delegating the execution to the associated path executor. + /// + /// + /// An array of representing the positions + /// used to compute the path in the grid-based operations. + /// public void Execute(FVector2[] positions) { var path = _resolver.GetPath(positions); - + if (path.HasValue) Executor.Execute(path.Value); } } \ No newline at end of file diff --git a/GridCasting/Models/GridGraph/GridGraphEdge.cs b/GridCasting/Models/GridGraph/GridGraphEdge.cs index 07272d8..c0029b2 100644 --- a/GridCasting/Models/GridGraph/GridGraphEdge.cs +++ b/GridCasting/Models/GridGraph/GridGraphEdge.cs @@ -8,12 +8,12 @@ public class GridGraphEdge(GridGraphNode nodeA, GridGraphNode nodeB, float angle /// /// Represents the starting node of the grid edge. /// - public GridGraphNode NodeA { get; } = nodeA; + public GridGraphNode NodeA { get; internal set; } = nodeA; /// /// Represents the ending node of the grid edge. /// - public GridGraphNode NodeB { get; } = nodeB; + public GridGraphNode NodeB { get; internal set; } = nodeB; /// /// Represents the angle of the grid edge in degrees. diff --git a/GridCasting/Models/Path.cs b/GridCasting/Models/Path.cs index 5d65a7c..33ac2bf 100644 --- a/GridCasting/Models/Path.cs +++ b/GridCasting/Models/Path.cs @@ -6,7 +6,7 @@ namespace GridCasting.Models; /// Represents a path structure consisting of a start node and a series of directions. /// The path is iterable, allowing iteration over the start node followed by the direction sequence. /// -public struct Path(int startNode, int[] directions) : IEnumerable +public struct Path(int startNode, params int[] directions) : IEnumerable { /// /// Gets or sets the starting node of the path. This represents the initial point diff --git a/GridCasting/Transform/GridResolver.cs b/GridCasting/Transform/GridResolver.cs index e380d1a..ed4507e 100644 --- a/GridCasting/Transform/GridResolver.cs +++ b/GridCasting/Transform/GridResolver.cs @@ -81,17 +81,98 @@ public class GridResolver /// - /// Creates a grid graph from a given grid structure, converting the grid's nodes into a graph format, - /// which enables advanced graph-based operations and transformations. + /// Creates a graph representation from the given grid structure. /// - /// The source grid structure containing nodes to be converted into a graph representation. + /// The grid structure containing nodes and their connections that should be converted into a graph. /// - /// A new instance of GridGraph representing the grid in a graph format if the conversion is successful; - /// otherwise, returns null if the grid cannot be converted. + /// A GridGraph instance representing the converted grid, or null if the grid is invalid + /// or cannot be successfully converted. /// - public static GridGraph? CreateGridGraph(Grid graph) + public static GridGraph? CreateGridGraph(Grid grid) { - throw new NotImplementedException(); + if (grid.Nodes.Count == 0) return null; + var graph = new GridGraph(); + var graphNodes = new Dictionary(); + var queue = new Queue<(GridNode? prev, GridNode curr)>(); + queue.Enqueue((null, grid.Nodes[0])); + + while (queue.TryDequeue(out var result)) + { + var (prev, curr) = result; + if (graphNodes.TryGetValue(curr, out var match)) continue; + + foreach (var connection in curr.Connections.OfType()) + queue.Enqueue((curr, connection)); + + var matches = 0; + var freeConnections = curr.Connections.Count(c => c != null); + foreach (var graphNode in graph) + { + if (graphNode.Edges.Count != curr.Connections.Count) continue; + + var usedPositions = graphNode.Edges.Count(edge => + { + var len = edge.NodeA == graphNode ? edge.Length : -edge.Length; + var position = curr.Position + new FVector2( + len * MathF.Cos(edge.Angle), + len * MathF.Sin(edge.Angle) + ); + // Add check for edge multiuse + return curr.Connections.Any(c => c != null && FVector2.Distance(c.Position, position) < 1e-4f); + }); + if (freeConnections != usedPositions) continue; + if (matches != 0) return null; // Multiple matches + match = graphNode; + matches++; + } + + if (match == null && freeConnections == curr.Connections.Count) // Create a new node only if there are no hanging edges + { + match = new GridGraphNode(); + foreach (var node in curr.Connections.OfType()) + { + var direction = node.Position - curr.Position; + var angle = (float)Math.Atan2(direction.Y, direction.X); + var len = direction.Length; + match.Edges.Add(new GridGraphEdge(match, null, angle, len)); + } + graph.Nodes.Add(match); + } + if (match == null) continue; + + graphNodes.Add(curr, match); + if (prev == null || !graphNodes.TryGetValue(prev, out var prevNode)) continue; + var linked = false; + foreach (var edge in from edge in prevNode.Edges + let len = edge.NodeA == prevNode ? edge.Length : -edge.Length + let position = prev.Position + new FVector2( + len * MathF.Cos(edge.Angle), + len * MathF.Sin(edge.Angle) + ) + where !(FVector2.Distance(curr.Position, position) >= 1e-4f) + select edge) + { + if (edge.NodeA == prevNode) + { + if (edge.NodeB != null && edge.NodeB != match) return null; + edge.NodeB = match; + } + else if (edge.NodeB == prevNode) + { + if (edge.NodeA != null && edge.NodeA != match) return null; + edge.NodeA = match; + } + else continue; + linked = true; + break; + } + if (!linked) return null; + } + + return graphNodes.Values.Distinct() + .Any(value => value.Edges.Any(edge => edge.NodeA == null || edge.NodeB == null)) + ? null + : graph; } @@ -201,6 +282,7 @@ public class GridResolver /// public Path? GetPath(FVector2[] positions) { + if (positions.Length == 0) return null; var point = GetNearestPoint(positions[0]); if (point == null) return null; var directions = new int[positions.Length - 1]; @@ -211,15 +293,17 @@ public class GridResolver var updated = false; for (var j = 0; j < node.Edges.Count; j++) { + var edge = node.Edges[j]; + var length = edge.NodeA == node ? edge.Length : -edge.Length; var newPos = position + new FVector2( - node.Edges[j].Length * MathF.Cos(node.Edges[j].Angle), - node.Edges[j].Length * MathF.Sin(node.Edges[j].Angle) + length * MathF.Cos(edge.Angle), + length * MathF.Sin(edge.Angle) ); if (FVector2.Distance(positions[i], newPos) > _sensitivity) continue; updated = true; directions[i - 1] = j; position = newPos; - node = node.Edges[j].NodeA == node ? node.Edges[j].NodeB : node.Edges[j].NodeA; + node = edge.NodeA == node ? edge.NodeB : edge.NodeA; break; } if (!updated) return null; // Path doesn't exist @@ -240,29 +324,30 @@ public class GridResolver var completedPoints = new HashSet(); PriorityQueue queue = new(); var threshold = _graphAABB.Size.Length; - var min = new GridGraphPoint(new FVector2(0, 0), _graph.Nodes[0]); + var min = _bvh.FindNearest(position) ?? new GridGraphPoint(new FVector2(0, 0), _graph.Nodes[0]); var minDistance = FVector2.Distance(position, min.TreePosition); queue.Enqueue(min, minDistance); while (queue.TryDequeue(out var point, out var priority)) { - if (priority < _sensitivity) break; if (!completedPoints.Add(point)) continue; if (_bvh.FindNearest(point.TreePosition, 1e-5f).Count == 0) _bvh.Add(point); if (priority < minDistance) { minDistance = priority; min = point; + if (priority < _sensitivity) break; } else if (priority > minDistance + threshold) break; foreach (var edge in point.Node.Edges) { var nextNode = edge.NodeA == point.Node ? edge.NodeB : edge.NodeA; + var length = edge.NodeA == point.Node ? edge.Length : -edge.Length; var dir = new FVector2( MathF.Cos(edge.Angle), MathF.Sin(edge.Angle) ); - var nextPosition = point.TreePosition + edge.Length * dir; + var nextPosition = point.TreePosition + length * dir; var nextPoint = new GridGraphPoint(nextPosition, nextNode); var dirToTarget = (position - point.TreePosition).Normalized; if (FVector2.Dot(dirToTarget, dir) < -0.3f) continue; @@ -301,9 +386,10 @@ public class GridResolver foreach (var edge in point.Node.Edges) { var nextNode = edge.NodeA == point.Node ? edge.NodeB : edge.NodeA; + var length = edge.NodeA == point.Node ? edge.Length : -edge.Length; var nextPosition = point.TreePosition + new FVector2( - edge.Length * MathF.Cos(edge.Angle), - edge.Length * MathF.Sin(edge.Angle) + length * MathF.Cos(edge.Angle), + length * MathF.Sin(edge.Angle) ); var nextPoint = new GridGraphPoint(nextPosition, nextNode); switch (callback(pointRepresentation, nextPoint)) @@ -332,7 +418,7 @@ public class GridResolver SkipNode, AbortTraversal } - + /// /// Represents a point in a grid graph, used within a 2D BVH (Bounding Volume Hierarchy) tree structure. @@ -346,7 +432,7 @@ public class GridResolver { public override FVector2 TreePosition { get; protected set; } = position; public GridGraphNode Node { get; } = node; - + private static FVector2 Quantize(FVector2 p) { const float eps = 0.001f; @@ -355,6 +441,24 @@ public class GridResolver MathF.Round(p.Y / eps) * eps ); } - public override int GetHashCode() => HashCode.Combine(Node, Quantize(TreePosition)); + + protected bool Equals(GridGraphPoint other) + { + return Quantize(TreePosition).Equals(Quantize(other.TreePosition)) && Node.Equals(other.Node); + } + + public override bool Equals(object? obj) + { + if (obj is null) return false; + if (ReferenceEquals(this, obj)) return true; + if (obj.GetType() != GetType()) return false; + return Equals((GridGraphPoint)obj); + } + + public override int GetHashCode() + { + return HashCode.Combine(Quantize(TreePosition), Node); + } } -} \ No newline at end of file +} + diff --git a/GridCasting/Transform/IPathTransform.cs b/GridCasting/Transform/IPathTransform.cs index c5f5e70..0fd651c 100644 --- a/GridCasting/Transform/IPathTransform.cs +++ b/GridCasting/Transform/IPathTransform.cs @@ -9,6 +9,15 @@ namespace GridCasting.Transform; /// public interface IPathTransform { + /// + /// Gets a value indicating whether this transformation is required. + /// + /// + /// A boolean indicating the necessity of the transformation. + /// If true, the transformation must be applied; if false, the transformation is optional. + /// + public bool IsRequired { get; } + /// /// Transforms the given path based on the specified grid graph. /// diff --git a/GridCasting/Utils/BVH/IReadOnlyPointBVH2D.cs b/GridCasting/Utils/BVH/IReadOnlyPointBVH2D.cs index 3c7dbf9..0d96983 100644 --- a/GridCasting/Utils/BVH/IReadOnlyPointBVH2D.cs +++ b/GridCasting/Utils/BVH/IReadOnlyPointBVH2D.cs @@ -1,7 +1,7 @@ using IgdrasilEngine.Engine.Math.Boxes; using IgdrasilEngine.Engine.Math.Vectors; -namespace GridCasting.Utils.BVH.Point; +namespace GridCasting.Utils.BVH; /// /// Интерфейс для чтения BVH дерева точек в 2D пространстве /// @@ -20,6 +20,14 @@ public interface IReadOnlyPointBVH2D where T : PointBVH2DTransform /// Радиус поиска. /// Список точек, найденных в пределах радиуса. public List FindNearest(FVector2 position, float radius); + + /// + /// Finds the nearest point in the BVH tree to the specified position. + /// + /// The position for which the nearest point is to be found. + /// The nearest point of type to the specified position. + public T? FindNearest(FVector2 position); + /// /// Находит все точки в пределах заданного радиуса от указанной позиции и добавляет их в предоставленный список. /// diff --git a/GridCasting/Utils/BVH/PointBVH2D.cs b/GridCasting/Utils/BVH/PointBVH2D.cs index e122606..30e48c1 100644 --- a/GridCasting/Utils/BVH/PointBVH2D.cs +++ b/GridCasting/Utils/BVH/PointBVH2D.cs @@ -1,5 +1,4 @@ -using GridCasting.Utils.BVH.Point; -using IgdrasilEngine.Engine.Math.Boxes; +using IgdrasilEngine.Engine.Math.Boxes; using IgdrasilEngine.Engine.Math.Vectors; namespace GridCasting.Utils.BVH; @@ -69,6 +68,14 @@ public class PointBVH2D : IReadOnlyPointBVH2D where T : PointBVH2DTransfor } } + public T? FindNearest(FVector2 position) + { + lock (_root) + { + return _root.FindNearestFwd(position); + } + } + /// /// Находит все точки в пределах заданного радиуса от указанной позиции и добавляет их в предоставленный список. /// @@ -191,6 +198,7 @@ public class PointBVH2D : IReadOnlyPointBVH2D where T : PointBVH2DTransfor /// Радиус поиска. /// Список для хранения найденных точек. public abstract void FindNearestFwd(FVector2 position, float radius, List result); + public abstract T? FindNearestFwd(FVector2 position); /// /// Находит все точки в пределах заданного радиуса от указанной позиции. /// @@ -517,6 +525,14 @@ public class PointBVH2D : IReadOnlyPointBVH2D where T : PointBVH2DTransfor Left?.FindNearestFwd(position, radius, result); Right?.FindNearestFwd(position, radius, result); } + + public override T? FindNearestFwd(FVector2 position) + { + if (!AABB.ContainsInclusive(position)) return null; + if (Left == null) return Right?.FindNearestFwd(position); + if (Right == null) return Left?.FindNearestFwd(position); + return FBox2.Distance(Left.AABB, position) < FBox2.Distance(Right.AABB, position) ? Left.FindNearestFwd(position) : Right.FindNearestFwd(position); + } /// /// Находит все точки в пределах заданного радиуса от указанной позиции. /// @@ -690,6 +706,9 @@ public class PointBVH2D : IReadOnlyPointBVH2D where T : PointBVH2DTransfor if (FVector2.Distance(position, _value.TreePosition) > radius) return; result.Add(_value); } + + public override T? FindNearestFwd(FVector2 position) => _value; + /// /// Находит все точки в пределах заданного радиуса от указанной позиции. /// diff --git a/GridCasting/Utils/BVH/PointBVH2DTransform.cs b/GridCasting/Utils/BVH/PointBVH2DTransform.cs index 4ced9ac..30b264a 100644 --- a/GridCasting/Utils/BVH/PointBVH2DTransform.cs +++ b/GridCasting/Utils/BVH/PointBVH2DTransform.cs @@ -1,5 +1,4 @@ -using GridCasting.Utils.BVH.Point; -using IgdrasilEngine.Engine.Math.Vectors; +using IgdrasilEngine.Engine.Math.Vectors; namespace GridCasting.Utils.BVH; diff --git a/GridCastingTests/ExecutorTests.cs b/GridCastingTests/ExecutorTests.cs new file mode 100644 index 0000000..68cc9f2 --- /dev/null +++ b/GridCastingTests/ExecutorTests.cs @@ -0,0 +1,72 @@ +using GridCasting.Executor; +using GridCasting.Models.GridGraph; +using Path = GridCasting.Models.Path; + +namespace GridCastingTests; + +public class ExecutorTests +{ + private GridGraph _graph; + private static readonly Path _path = new(0, 1, 1, 2, 3); + [SetUp] + public void Setup() + { + // Create a simple hex grid + _graph = new GridGraph(); + var node = new GridGraphNode(); + for (var i = 0; i < 6; i++) + node.Edges.Add(new GridGraphEdge(node, node, MathF.PI * i / 3, 1)); + _graph.Nodes.Add(node); + } + + [Test] + public void TestNoCommands() + { + var executor = new PathExecutor(_graph, []); + Assert.That(executor.Execute(_path), Is.False, "Executor should not execute without commands"); + } + + [Test] + public void TestWrongCommand() + { + var executor = new PathExecutor(_graph, []); + executor.AddCommand(new TestPassedCommand(), _path); + + Assert.Multiple(() => + { + Assert.That(executor.Execute(new Path(0, 1, 2, 1)), Is.False, "Executor should not execute with wrong command"); + }); + } + + [Test] + public void TestCommandExecution() + { + var executor = new PathExecutor(_graph, []); + executor.AddCommand(new TestPassedCommand(), _path); + + Assert.Multiple(() => + { + Assert.That(executor.Execute(_path), Is.True, "Executor should execute with commands"); + }); + } + + [Test] + public void TestCommandFamily() + { + var executor = new PathExecutor(_graph, []); + executor.AddCommand(new TestPassedCommand(), new Path(0, 1, 1, 2), true); + + Assert.Multiple(() => + { + Assert.That(executor.Execute(_path), Is.True, "Executor should execute with commands"); + }); + } + + public class TestPassedCommand : ICommand + { + public void Execute(CommandContext context) + { + Assert.That(context.Command, Is.EqualTo(_path), "Command executed successfully"); + } + } +} \ No newline at end of file diff --git a/GridCastingTests/GridCastingTests.csproj b/GridCastingTests/GridCastingTests.csproj new file mode 100644 index 0000000..8040677 --- /dev/null +++ b/GridCastingTests/GridCastingTests.csproj @@ -0,0 +1,28 @@ + + + + net8.0 + enable + enable + + false + true + + + + + + + + + + + + + + + + + + + diff --git a/GridCastingTests/GridResolverTests.cs b/GridCastingTests/GridResolverTests.cs new file mode 100644 index 0000000..bf10fe8 --- /dev/null +++ b/GridCastingTests/GridResolverTests.cs @@ -0,0 +1,127 @@ +using GridCasting.Models.GridGraph; +using GridCasting.Transform; +using IgdrasilEngine.Engine.Math.Boxes; +using IgdrasilEngine.Engine.Math.Vectors; + +namespace GridCastingTests; + +public class GridResolverTests +{ + private GridResolver _resolver; + private static readonly int[] Expected = [0, 2, 1]; + + [SetUp] + public void Setup() + { + // Create a simple hex grid + var graph = new GridGraph(); + var node = new GridGraphNode(); + for (var i = 0; i < 6; i++) + node.Edges.Add(new GridGraphEdge(node, node, MathF.PI * i / 3, 1)); + graph.Nodes.Add(node); + + _resolver = new GridResolver( + graph, + 0.1f + ); + } + + [Test] + public void TestWorkingPath() + { + IVector3[] points = [ + new(7, 2, 5), + new(7, 2, 6), + new(7, 3, 6) + ]; + var positions = points.Select(p => + { + var result = FVector2.Zero; + for (var i = 0; i < 3; i++) + { + var angle = MathF.PI * i / 3; + var value = i switch + { + 0 => p.X, + 1 => p.Y, + 2 => p.Z, + _ => throw new ArgumentOutOfRangeException(nameof(i)) + }; + result += new FVector2( + value * MathF.Cos(angle), + value * MathF.Sin(angle) + ); + } + return result; + }).ToArray(); + var path = _resolver.GetPath(positions); + Assert.Multiple(() => + { + Assert.That(path.HasValue, Is.True, "Path is null"); + Assert.That(path.Value, Is.EqualTo(Expected), "Path is incorrect"); + }); + + } + + [Test] + public void TestRippedPath() + { + IVector3[] points = [ + new(7, 2, 5), + new(7, 2, 6), + new(7, 4, 6) + ]; + var positions = points.Select(p => + { + var result = FVector2.Zero; + for (var i = 0; i < 3; i++) + { + var angle = MathF.PI * i / 3; + var value = i switch + { + 0 => p.X, + 1 => p.Y, + 2 => p.Z, + _ => throw new ArgumentOutOfRangeException(nameof(i)) + }; + result += new FVector2( + value * MathF.Cos(angle), + value * MathF.Sin(angle) + ); + } + return result; + }).ToArray(); + var path = _resolver.GetPath(positions); + Assert.That(path.HasValue, Is.False, "Path is not null"); + } + + [Test] + public void TestEmptyPath() + { + FVector2[] positions = []; + var path = _resolver.GetPath(positions); + Assert.That(path.HasValue, Is.False, "Path is not null"); + } + + [Test] + public void TestGrid() + { + var positions = _resolver.GetGridPositions(new FBox2(FVector2.One * -5, FVector2.One * 5)); + var invSqrt3 = 1f / MathF.Sqrt(3); + Assert.Multiple(() => + { + foreach (var pos in positions) + { + var x = float.Abs(pos.X - invSqrt3 * pos.Y); + var y = float.Abs(2 * invSqrt3 * pos.Y); + x -= (int)x; + y -= (int)y; + if (x > 0.5) x -= 1; + if (y > 0.5) y -= 1; + + Assert.That(x, Is.EqualTo(0).Within(0.001f), $"Position {pos} is not on the grid"); + Assert.That(y, Is.EqualTo(0).Within(0.001f), $"Position {pos} is not on the grid"); + } + }); + } +} \ No newline at end of file diff --git a/guidinturtle.yml b/guidinturtle.yml new file mode 100644 index 0000000..efa8c09 --- /dev/null +++ b/guidinturtle.yml @@ -0,0 +1,52 @@ +# GuidingTurtle Configuration File +# Конфигурация генератора документации + +# Настройки информации о проекте +project: + solution: "GridCasting.sln" + name: "Grid Casting" + version: "1.0.0" + description: "Библиотека для распознавания и исполнения символьных команд" +# homepage: "https://github.com/Igdrasil-Engine/IgdrasilEngine" + private-projects: + - GridCastingTests + + include-private-projects: true + +# Параметры входной документации и структуры +generator: + template-path: "Templates" + default-template-name: "page" + error-template-name: "error" + content-path: "Docs" + include-private-docs: true + debug: true + index-page-names: + - "index.md" + +# Настройки API экстракции и анализа кода +api: + enable-api-extraction: true + include-non-public-members: true + include-remarks: true + doc-config: + layout: "api" + +# Параметры вывода и оформления результата +output: + output-path: "docs" + +# Настройки кеша рендера +cache: + {} + +# Правила построения навигации +navigation: + base-url: "/dev" + +# Настройки перекрестных ссылок между API и гайдами +linker: + api-path: "api" + docs-path: "docs" + enable-markdown-api-links: true + enable-api-markdown-links: true