📘 ДОКУМЕНТАЦІЯ Tryzillya TreeLab v1.2

Процедурна генерація рослин для Unreal Engine 5.6.1/5.7.1

Дата актуальності: 01.01.2026 Версія плагіну: 1.2 Розробник: ZOAZ (Tryzillya.st) Платформа продажу: Fab

⚠️ ВАЖЛИВЕ ПОПЕРЕДЖЕННЯ

Ця документація не є гарантовано актуальною через можливі оновлення плагіна. Unreal Engine та його API регулярно змінюються, що може вплинути на структуру файлів, функції та поведінку плагіна. Перед внесенням змін перевіряйте актуальність інформації. Документація актуальна виключно для версії 1.2 станом на 01.01.2026. Будь-яке втручання в код плагіна може призвести до нестабільної роботи та втрати підтримки.

🌲 1. ВСТУП ТА МОЖЛИВОСТІ

Tryzillya TreeLab — це процедурний генератор дерев та рослин для Unreal Engine, який дозволяє створювати унікальні рослинні моделі за лічені секунди. Плагін інтегрується в редактор UE та надає зручний UI для керування параметрами генерації.

Ключові можливості:

💻 2. ТЕХНІЧНІ ВИМОГИ

Параметр Мінімум Рекомендовано
Unreal Engine 5.6.1 5.7.1+
OS Windows 10/11 x64 Windows 11
RAM 8 GB 16+ GB
GPU DirectX 12 compatible RTX 3060+
Dependencies ProceduralMeshComponent (включено) -
Build Configuration Development Editor Shipping

Модулі за замовчуванням:

📦 3. ВСТАНОВЛЕННЯ ТА АКТИВАЦІЯ

Крок 1: Завантаження

  1. Придбайте плагін на Fab
  2. Завантажте архів Tryzillya_TreeLab_v1.2.zip

Крок 2: Інсталяція

# Шлях для встановлення:
[YourProject]/Plugins/Tryzillya_TreeLab/

Крок 3: Активація

  1. Відкрийте проект в Unreal Editor
  2. Edit → Plugins → Installed → Tools
  3. Увімкніть Tryzillya TreeLab
  4. Перезапустіть редактор
  5. Плагін з'явиться в меню: Window → Tryzillya TreeLab

Крок 4: Підтвердження

  • Перевірте наявність іконки 🌲 на панелі інструментів
  • Відкрийте вкладку, натиснувши на іконку

📂 4. СТРУКТУРА ПЛАГІНА

Tryzillya_TreeLab/
├───Binaries/Win64/                    # Скомпільовані DLL (UnrealEditor-*.dll)
├───Config/                            # Конфігураційні файли (не використовується)
├───Content/                           # Ассети плагіну
│   └───Content/                       # Додатковий рівень вкладеності
│       ├───Mat/                       # Матеріали (M_Birch, M_Pine, M_Oak)
│       ├───PresentLevel/              # Демонстраційний рівень
│       ├───PresentsTrees/             # Збережені дерева (Static Meshes)
│       │   ├───Birch/
│       │   ├───Pine/
│       │   └───Oak/
│       └───Tex/                       # Текстури (PBR maps)
├───Intermediate/Build/                # Файли компіляції (генерується автоматично)
├───Resources/                         # Іконки плагіну (TreeLab_40.png, TreeLab_20.png)
└───Source/Tryzillya_TreeLab/        # Вихідний код
    ├───Private/                       # Реалізація (.cpp)
    └───Public/                        # Заголовки (.h)

🔧 5. ДЕТАЛЬНИЙ ОПИС ФАЙЛІВ

📁 /Source/Tryzillya_TreeLab/Public/ (Заголовки)

5.1 TreeGenerator.h

Роль: Центральний модуль генерації геометрії

USTRUCT(BlueprintType) FTreeSettings

Призначення: Структура, що містить 100+ параметрів генерації. Поділяється на категорії:

  • Seed: Унікальний ідентифікатор дерева (Seed, Preset, Type)
  • Global: Масштаб (Scale)
  • Trunk: Форма стовбура (Height, Radius, Sides, Segments, Taper, Curve)
  • Deformation: Реалістичність (Bend, Gravity, Twist, Noise)
  • Branches: Основні гілки (Count, Length, Radius, Segments, Spread)
  • SubBranches: Саб-гілки (Probability, Scale, MaxCount)
  • Leaves: Листя (Enable, Count, Size, Density, Variation)
  • Materials: TrunkMaterial, LeafMaterial
  • LOD: Levels (Count, DistanceStep, ReductionPercent)
  • Misc: Капи (CloseTop, BottomCap)

Клас FTreeGenerator:

  • GenerateTree() — головний метод, що створює AActor з повною ієрархією компонентів
  • SaveTreeAsStaticMesh() — конвертація процедурної геометрії в UStaticMesh з LOD
  • BuildStaticMeshFromProcedural() — копіювання вершин, нормалей, UV з UProceduralMeshComponent у FMeshDescription

5.2 TreeLabWidget.h

Роль: UI панель керування

class STreeLabWidget : public SCompoundWidget

Призначення: Slate UI для візуального редагування FTreeSettings

Ключові члени:

  • CurrentSettings — поточні параметри генерації
  • LastGeneratedActor — посилання на останнє згенероване дерево
  • PresetBirch/Pine/Oak — жорстко закодовані пресети
  • MaterialBirch/Oak/Pine — посилання на матеріали

Методи UI:

  • BuildSection() — створює розкриваючийся блок (SExpandableArea)
  • BuildTrunkSection() — UI для стовбура
  • BuildBranchesSection() — UI для гілок
  • BuildLeavesSection() — UI для листя
  • BuildLODSection() — UI для рівнів деталізації

5.3 Tryzillya_TreeLab.h

Роль: Головний модуль плагіну

class FTryzillya_TreeLabModule : public IModuleInterface

Призначення: Реєстрація плагіну в системі модулів UE

Ключові методи:

  • StartupModule() — викликається при запуску редактора
    • Реєструє команди (Commands)
    • Реєструє Nomad Tab (вкладку в редакторі)
    • Додає розширення меню (Menu Extender)
  • ShutdownModule() — очищення ресурсів
  • OnSpawnPluginTab() — створення екземпляру STreeLabWidget

5.4 Tryzillya_TreeLabCommands.h

Роль: Команда відкриття вікна

class FTryzillya_TreeLabCommands : public TCommands<FTryzillya_TreeLabCommands>

Призначення: UI_COMMAND для кнопки на панелі інструментів

Команда: OpenPluginWindow — прив'язана до FInputChord() (Ctrl+Shift+T можна додати)

5.5 Tryzillya_TreeLabStyle.h

Роль: Завантаження іконок

class FTryzillya_TreeLabStyle

Призначення: Завантажує PNG-іконки з /Resources/ та реєструє їх в SlateStyle

Іконки:

  • TreeLab_40.png (40x40) — для панелі інструментів
  • TreeLab_20.png (20x20) — для меню

📁 /Source/Tryzillya_TreeLab/Private/ (Реалізація)

5.6 TreeGenerator.cpp

Роль: Ядро алгоритму генерації

ComputeNormalsFromTriangles()
  • Обчислює вершинні нормалі через суму нормалей прилеглих трикутників
  • Використовує FVector::CrossProduct() для обчислення фейсових нормалей
  • Вирівнювання: якщо сума нормалей ≈ 0, встановлює UpVector
CreateCylinderMesh()
  • Параметри: масив центральних точок, радіуси, кількість сторін
  • Генерація кілець: для кожної точки створює Sides+1 вершин (UV seam fix)
  • UV: U = i / Sides, V = t — без шва завдяки додатковій вершині
  • Triangles: два трикутники на квад (i0,i3,i2) та (i0,i1,i3)
  • Normals: викликає ComputeNormalsFromTriangles
GenerateTree() — Головний цикл:
  1. Видаляє попереднє дерево (CleanupPreviousTree)
  2. Створює Root AActor з компонентом USceneComponent
  3. Генерація стовбура:
    • Створює центральну лінію з Perlin noise (BendAmount)
    • Додає гравітаційний ефект (gravityPull = -Settings.Gravity * t² * 5.0f)
    • Викликає CreateCylinderMesh
  4. Генерація основних гілок (BranchCount):
    • Випадковий кут angle та висота heightT
    • Напрямок на основі сферичних координат
    • Кожна гілка має свій UProceduralMeshComponent
    • Саб-гілки: якщо Rand() < SubBranchProbability, генерує аж до MaxSubBranchesPerBranch
  5. Генерація листя (LeafCount):
    • Для кожної гілки викликається GenerateLeavesForBranch
    • Листя — це quad (4 вершини, 2 трикутники)
    • Орієнтація по нормалі гілки + RandomTilt
  6. Збереження в StaticMesh: якщо LODCount > 0
  7. Актор отримує лейбл Generated_Tree_{Seed}
SaveTreeAsStaticMesh()
  • Використовує FMeshDescription для опису геометрії
  • LOD: SetNumSourceModels(LODCount) + ReductionSettings.PercentTriangles
  • Колізія: CreateBodySetup() + CTF_UseSimpleAsComplex + FKSphylElem (капсула)
  • Реєстрація: Package::MarkPackageDirty() + AssetRegistry::AssetCreated
BuildStaticMeshFromProcedural()
  • Копіює дані з кожного UProceduralMeshComponent
  • LOD0: повна геометрія
  • LOD1+: кожен N-й трикутник (TriangleSkipFactor)
  • Materials: мапить матеріали на PolygonGroups

5.7 TreeLabWidget.cpp

Роль: 1000+ рядків UI-коду

Construct()

Створює вертикальний лейаут з 5 секціями:

  1. Заголовок з іконкою 🌲
  2. Кнопки: Reset, Generate Tree (зелена), Save Mesh (синя)
  3. Скролл-контейнер з усіма параметрами
  4. Контактна кнопка з посиланням на http://tryzillyast.zzz.com.ua
OnGenerateClicked()
  1. Отримує GEditor->GetWorldContexts() Editor World
  2. Викликає FTreeGenerator::GenerateTree()
  3. Вибирає актор в редакторі (GEditor->SelectActor)
  4. Діагностика: DebugLogComponentMaterials() — логує всі матеріали компонентів
OnSaveClicked()
  1. Відкриває Save Asset Dialog (FSaveAssetDialogConfig)
  2. Шлях збереження: /Game/Generated_Trees/
  3. Викликає FTreeGenerator::SaveTreeAsStaticMesh()
  4. Показує спливаюче сповіщення (Success/Failed)
EnsureDefaultMaterials()
  • Шляхи пошуку:
    1. /Tryzillya_TreeLab/Materials/ (плагін)
    2. /Game/Materials/ (проект)
  • Якщо матеріал не знайдений, пробує LoadObject з явних шляхів
  • Пріоритет: SearchPaths → Explicit paths → Game fallback
  • Логіка призначення:
    • Якщо назва компонента містить "leaf" → LeafMaterial
    • Якщо назва містить "trunk/branch" → TrunkMaterial
    • Інакше: перевірка поточного матеріалу компонента
ApplyMaterialsToActor()
  • Діагностика: UE_LOG з емодзі (🔴⚠️✅🎨)
  • Проходить по всіх UMeshComponents
  • Викликає SetMaterial(i, Material) для кожного слота

5.8-5.10 Tryzillya_TreeLab.cpp/.Commands.cpp/.Style.cpp

  • Tryzillya_TreeLab.cpp: Реєстрація Nomad Tab, Menu Extension, Toolbar Button
  • Commands.cpp: Реєстрація команди з LOCTEXT
  • Style.cpp: Завантаження PNG з /Resources/, реєстрація в FSlateStyleRegistry

5.11 Tryzillya_TreeLab.Build.cs

Критичні залежності:

Public: "ProceduralMeshComponent", "MeshDescription", "StaticMeshDescription"
Private (Editor): "UnrealEd", "AssetTools", "ContentBrowser", "PropertyEditor"

Примітка: Плагін типу Editor, тому не працює в Runtime/Build без перекомпіляції.

5.12 Tryzillya_TreeLab.uplugin

{
  "VersionName": "1.2",
  "EngineVersion": "5.7.1",
  "Type": "Editor",
  "CanContainContent": true
}

Важливо: "Type": "Editor" — плагін активний лише в редакторі. Для Runtime-підтримки потрібно змінити на "Type": "Runtime" та додати відповідні модулі.

🎯 6. ФУНКЦІОНАЛЬНІ МОЖЛИВОСТІ

6.1 Генерація геометрії

6.2 Матеріали

6.3 LOD System

6.4 Пам'ять та продуктивність

🎨 7. ПРЕСЕТИ ТА ЇХ ЛОГІКА

7.1 Birch (Береза)

TrunkHeight = 1600.f, TrunkRadius = 20.f
Taper = 0.08f, TaperCurve = 28.1f
BendAmount = 100.0f, Gravity = 8.0f
BranchCount = 12, BranchLength = 420.f
BranchCurl = 8.0f, BranchSpread = 45°
LeafCount = 39, LeafSize = 95.f
LeafDensity = 1.2f, LeafSizeVariation = 0.3f

Логіка: Витончений стовбур, багато дрібного листя, помірна кривизна. Підходить для лісових сцен.

7.2 Pine (Сосна)

TrunkHeight = 1700.f, TrunkRadius = 40.f
Taper = 0.06f, TaperCurve = 0.03f
BendAmount = 35.0f, Gravity = 2.0f
BranchCount = 18, BranchLength = 360.f
BranchCurl = 12.0f, BranchSpread = 60°
LeafCount = 20, LeafSize = 100.f
LeafDensity = 1.0f, LeafRandomTilt = 0.6f

Логіка: Товстий стовбур, багато коротких гілок, мала гравітація (хвойні дерева стоять прямо). Листя як хвоїнки.

7.3 Oak (Дуб)

TrunkHeight = 1500.f, TrunkRadius = 45.f
Taper = 0.12f, TaperCurve = 0.15f
BendAmount = 10.0f, Gravity = 9.0f
BranchCount = 7, BranchLength = 820.f
BranchTaper = 0.1f, BranchSpread = 80°
LeafCount = 27, LeafSize = 240.f
LeafRandomTilt = 100.0f

Логіка: Масивний стовбур, товсті довгі гілки, велике листя, сильна гравітація (важкі гілки провисають). Підходить для паркових сцен.

7.4 Чому саме такі значення?

  • TaperCurve: Визначає, як швидко стовбур стає тоншим. Для берези високе значення (28.1) — різкий перехід.
  • Gravity: Для хвойних — низьке (2.0), бо гілки короткі та пружні. Для дуба — високе (9.0), бо гілки важкі.
  • BranchHorizontalSpread: Сосна має 0.95 (гілки виходять майже горизонтально), дуб — 0.6 (обплітає стовбур).
  • LeafSize: Дуб — 240 (велике листя), береза — 95 (дрібне), сосна — 100 (хвоїнки).

🖥️ 8. ІНТЕРФЕЙС КОРИСТУВАЧА (UI/UX)

8.1 Головне вікно

8.2 Контроли

8.3 Діагностика

🔌 9. API ДЛЯ РОЗРОБНИКІВ

9.1 Генерація через C++

#include "TreeGenerator.h"

FTreeSettings Settings;
Settings.Seed = 12345;
Settings.Type = TEXT("CustomTree");
Settings.TrunkHeight = 2000.f;
Settings.BranchCount = 15;

AActor* Tree = FTreeGenerator::GenerateTree(
    GEditor->GetEditorWorldContext().World(),
    FTransform(FVector(0,0,0)),
    Settings
);

9.2 Збереження в StaticMesh

UStaticMesh* Mesh = FTreeGenerator::SaveTreeAsStaticMesh(
    Tree,
    TEXT("/Game/MyTrees/CustomTree_StaticMesh"),
    Settings
);

9.3 Кастомний пресет

// Додайте в STreeLabWidget::InitPresetTemplates()
FTreeSettings PresetCustom;
PresetCustom.Preset = 3; // Новий ID
PresetCustom.Type = TEXT("Palm");
PresetCustom.TrunkHeight = 3000.f;
PresetCustom.BranchCount = 5;
// ...

🛠️ 10. РОЗШИРЕННЯ ТА КАСТОМІЗАЦІЯ

10.1 Додавання нового пресету

  1. В TreeLabWidget.h додайте FTreeSettings PresetYourName;
  2. В TreeLabWidget.cpp:
    • В InitPresetTemplates() ініціалізуйте параметри
    • В PopulatePresetOptions() додайте PresetOptions.Add(MakeShared<FString>(TEXT("YourName")));
    • В ApplyPreset() додайте else if (Name == TEXT("YourName")) ApplyPreset(3);
  3. Створіть матеріали M_YourName та M_YourName_Leaf в /Content/Mat/
  4. Перекомпілюйте плагін

10.2 Зміна алгоритму генерації

10.3 Runtime-підтримка

  1. Змініть "Type": "Editor" на "Type": "Runtime" в .uplugin
  2. Перенесіть PrivateDependencyModuleNames з if (Target.bBuildEditor) до Public
  3. Додайте RTTI та PhysicsCore в PublicDependencyModuleNames
  4. Перекомпілюйте для Shipping

❗ 11. ВІДЛАГОДЖЕННЯ ТА ПОМИЛКИ (TROUBLESHOOTING)

11.1 Помилка: "Failed to save static mesh"

Причина: Некоректний шлях або права доступу

Рішення: Перевірте SaveAssetPath, переконайтесь що /Game/ існує

11.2 Матеріали не застосовуються

Причина: Матеріали не знайдені в /Tryzillya_TreeLab/Materials/

Рішення:

  • Відкрийте Content Browser → View Options → Show Plugin Content
  • Перевірте наявність матеріалів в Tryzillya_TreeLab папці
  • Вручну присвойте матеріали в UI

11.3 Високий FPS Drop

Причина: Занадто високі значення (LeafCount > 100, BranchCount > 50)

Рішення: Зменшіть LODReductionPercent до 50% та LODDistanceStep до 1000

11.4 Crash при генерації

Причина: nullptr World або недостатня пам'ять

Рішення: Переконайтесь, що відкритий рівень в редакторі (EWorldType::Editor)

11.5 Проблеми з колізією

Причина: BodySetup не створюється для LOD0

Рішення: В SaveTreeAsStaticMesh() додайте StaticMesh->GetBodySetup()->InvalidatePhysicsData();

📞 12. КОНТАКТИ ТА ПІДТРИМКА

  • Розробник: ZOAZ (Tryzillya.st)
  • Email: tymurofficedev@gmail.com
  • Офіційний сайт: http://tryzillyast.zzz.com.ua
  • Підтримка: Через FAB або email
  • Документація: Оновлення публікуються на сайті
  • Discord: (Посилання додається розробником)

12.1 Як повідомити про баг

  1. Зробіть скріншот Output Log (Window → Output Log)
  2. Експортуйте налаштування (зробіть фото UI)
  3. Надішліть на email з темою [BUG] TreeLab v1.2

12.2 Запити на нові фічі

Наші ігри

Кожна наша гра — це експеримент і виклик. Ми ділимось із вами найкращим, що створили.