Progression Tree Builder

Introduction

This guide covers advanced usage patterns and best practices for Progression Tree Builder. Learn how to implement roguelike progression, create complex skill dependencies, and optimize your trees.

Traditional Skill Trees

Creating a Character Class Tree

Example: Warrior skill tree with three branches (Offense, Defense, Utility)

Warrior Skills
├── Offense Branch
│   ├── Basic Strike (root)
│   ├── Power Strike (requires: Basic Strike)
│   └── Execute (requires: Power Strike)
│
├── Defense Branch
│   ├── Block (root)
│   ├── Parry (requires: Block)
│   └── Fortress (requires: Parry)
│
└── Utility Branch
    ├── Dash (root)
    └── Sprint (requires: Dash)

Latest Mode (Roguelike Progression)

Setup Latest Mode

1. Assign Selection Weights

   For each skill in your tree, set the Selection Weight field:

   Rarity	Weight	Frequency
   Common	70-100	Very Frequent
   Uncommon	40-70	Frequent
   Rare	20-40	Occasional
   Epic	10-20	Rare
   Legendary	1-10	Very Rare

2. Configure UI Controller

   Select your ProgressionTreeUIController in the scene:

   • • Set Layout Mode = Latest
   • • Set Latest Node Count = 3 (or 2-6)
   • • Enable Auto Refresh On All Maxed
   • • Set Column Width = 0 (auto-fit) or fixed value
3. Setup Latest Mode Controller

   Create a child GameObject under your UI with:

   • • Add LatestModeLayoutController component
   • • Create child GameObject "DetailsContainer" with RectTransform
   • • Assign your ProgressionDetailsUI prefab
   • • Reference controller in ProgressionTreeUIController
4. Test & Iterate

   Press Play and award points to see random skills appear. Adjust weights as needed.

Example: Survivors-Style Game

Complete example for a level-up based progression system:

Combat Skills (15 total)
├── Pistol Path (5 skills)
│   ├── Basic Pistol (Weight: 80, Rank: 1)
│   ├── Rapid Fire (Weight: 60, Rank: 2)
│   ├── Armor Pierce (Weight: 40, Rank: 3)
│   ├── Explosive Rounds (Weight: 25, Rank: 3)
│   └── Infinite Ammo (Weight: 10, Rank: 1)
│
├── Shotgun Path (5 skills)
│   └── ... (similar structure)
│
└── Rifle Path (5 skills)
    └── ... (similar structure)

Trigger: On Character Level Up
├── Instruction: Award Progression Points
│   ├── Tree: [Combat Skills]
│   └── Amount: 1
│
├── Instruction: Refresh Latest Pool
│   ├── Tree: [Combat Skills]
│   ├── Node Count: 3
│   └── Only If All Maxed: false
│
└── Instruction: Open Progression Tree UI
    └── Tree: [Combat Skills]

Custom Layout Strategies

Create custom positioning logic for skill nodes by implementing the ILayoutStrategy interface. This allows you to create unique tree visualizations beyond the built-in Grid, Graph, and List modes.

When to Use Custom Layouts

Custom layout strategies are perfect for:

• Wider or narrower grid columns than default
• Custom spacing between nodes
• Game-specific visual requirements
• Adapting to different screen sizes or aspect ratios

Creating a Custom Strategy

1. Create Strategy ScriptableObject

   Create a new C# script that inherits from ScriptableObject and implements ILayoutStrategy:

   using UnityEngine;
   using ProgressionTreeBuilder.Runtime.Core;
   using ProgressionTreeBuilder.Runtime.UI.Controllers;
   using ProgressionTreeBuilder.Runtime.UI.Layout;
   using System.Collections.Generic;
   
   [CreateAssetMenu(fileName = "MyLayout", 
       menuName = "Progression Tree Builder/Custom Layout")]
   public class MyLayoutStrategy : ScriptableObject, ILayoutStrategy
   {
       [Header("Grid Configuration")]
       [Range(1, 10)]
       public int columns = 2;  // Fewer columns = wider
       
       public Vector2 cellSize = new Vector2(400f, 200f);
       public Vector2 cellSpacing = new Vector2(20f, 20f);
       public RectOffset padding = new RectOffset(10, 10, 10, 10);
       
       public void Prepare(ProgressionTreeUIController controller)
       {
           // Modify layoutSettings BEFORE layout components are created
           controller.layoutSettings.gridColumns = columns;
           controller.layoutSettings.gridCellSize = cellSize;
           controller.layoutSettings.gridCellSpacing = cellSpacing;
           controller.layoutSettings.gridPadding = padding;
       }
       
       public Dictionary<ProgressionSkill, Vector2> CalculatePositions(
           ProgressionTree tree,
           LayoutSettings settings)
       {
           // For Grid/List modes, return empty dictionary
           // Unity's LayoutGroup handles positioning automatically
           return new Dictionary<ProgressionSkill, Vector2>();
       }
       
       public string GetLayoutName()
       {
           return "My Custom Layout";
       }
   }

2. Create Strategy Asset

   Right-click in Project window → Create → Progression Tree Builder → Custom Layout

   Configure your desired column count, cell size, and spacing in the Inspector.

3. Assign to UI Controller

   Select your UI Controller GameObject and assign the strategy asset to theCustom Layout Strategy Object field.

Example: Wide Column Grid

The Examples package includes a GridLayoutStrategy that demonstrates creating a wider 2-column grid layout:

// GridLayoutStrategy Configuration
[Range(1, 10)]
public int columns = 2;  // Only 2 columns

public Vector2 cellSize = new Vector2(1111f, 180f);  // Much wider cells
public Vector2 cellSpacing = new Vector2(15f, 15f);
public RectOffset padding = new RectOffset(10, 10, 10, 10);

public void Prepare(ProgressionTreeUIController controller)
{
    // Apply custom settings
    controller.layoutSettings.gridColumns = columns;
    controller.layoutSettings.gridCellSize = cellSize;
    controller.layoutSettings.gridCellSpacing = cellSpacing;
    controller.layoutSettings.gridPadding = padding;
    
    Debug.Log($"[GridLayoutStrategy] Applied {columns} columns");
}

This configuration creates a cleaner, wider layout perfect for games with detailed skill descriptions or large skill icons.

Advanced: Custom Position Calculation

For Graph mode or custom positioning needs, implementCalculatePositions() to return a dictionary mapping skills to their exact positions:

public Dictionary<ProgressionSkill, Vector2> CalculatePositions(
    ProgressionTree tree,
    LayoutSettings settings)
{
    var positions = new Dictionary<ProgressionSkill, Vector2>();
    
    // Example: Diagonal layout
    for (int i = 0; i < tree.skills.Count; i++)
    {
        var skill = tree.skills[i];
        float x = i * settings.horizontalSpacing;
        float y = i * -settings.verticalSpacing;  // Descending diagonal
        
        positions[skill] = new Vector2(x, y);
    }
    
    return positions;
}

Best Practices

Choice Groups

Choice Groups force players to choose between mutually exclusive options. Perfect for class specializations.

Example: Class Selection

Root Skill: "Choose Your Path"
├── Choice Group: "Combat Style"
│   ├── Warrior Path (melee focus)
│   ├── Ranger Path (ranged focus)
│   └── Mage Path (magic focus)
│
→ Player can only choose ONE of these three paths

Game Creator Instructions

Skills support two types of instruction execution for maximum flexibility: Asset-Based (in ScriptableObject) and Scene-Based (via SkillInstructions Component).

Asset-Based Instructions

Configure directly in your ProgressionSkill node in the Graph Editor. Available events: On Skill Unlocked, On Skill Activated, On Skill Upgrade

Example: Power Strike Skill (Asset-Based)

On Skill Unlocked:
├── Change Stat: +10 Attack Damage
├── Play Audio: unlock_sound.wav
└── Show Message: "Power Strike Learned!"

On Skill Activated:
├── Play Animation: power_strike_cast
├── Wait: 0.3 seconds
└── Spawn Prefab: strike_effect (from Resources)

On Skill Upgrade:
└── Play Audio: rank_up.wav

Scene-Based Instructions

For scene-specific behavior with GameObject references, use the SkillInstructions component.

Example: UI Feedback (Scene-Based)

GameObject: "PowerStrike_Instructions"
└── SkillInstructions Component
    ├── Skill: [Power Strike]
    │
    ├── ☑ On Unlocked
    │   └── Instructions:
    │       ├── Set Active: UIPanel "SkillUnlockedPanel" → True
    │       ├── Change Text: TextMeshPro "SkillNameText" → "Power Strike"
    │       ├── Wait: 2 seconds
    │       └── Set Active: UIPanel "SkillUnlockedPanel" → False
    │
    ├── ☑ On Activated
    │   └── Instructions:
    │       ├── Instantiate Prefab: StrikeVFX at Transform "CastPoint"
    │       ├── Camera Shake: MainCamera (intensity 0.5)
    │       └── Set Active: GameObject "ImpactEffect" → True
    │
    └── ☐ On Upgrade (disabled)

When to Use Which Approach

Game Creator 2 Stats Integration

Skills can automatically modify character stats when unlocked or upgraded.

Adding Stat Modifiers

1. Select a ProgressionSkill asset
2. In Inspector, find "Stat Modifiers" section
3. Click "Add Stat Modifier"
4. Select Target Stat (from your GC2 Stats)
5. Set Value and Modifier Type

Example: Health Skill

Skill: "Vitality"
├── Type: Passive
├── Max Rank: 5
├── Cost: 1 per rank
└── Stat Modifiers:
    └── Target Stat: Max Health
        ├── Type: Per Rank
        └── Value: +10

Result:
Rank 1 → +10 Health
Rank 2 → +20 Health
Rank 3 → +30 Health
...
Rank 5 → +50 Health

Setup: Skill Instruction Manager

One-Time Setup

1. Locate your ProgressionTreeManager GameObject

   This is the GameObject that has the ProgressionTreeManager component attached

2. Add SkillInstructionManager component

   Add Component → Progression Tree Builder → Skill Instruction Manager

3. Configure Auto-Discovery (Optional)

   By default, the manager searches the entire scene on Awake. You can limit it to children only or disable auto-find.

Manager Properties

Workflow: Creating Scene Instructions

1. Open Graph Editor & Select Skill

   Open your ProgressionTree Graph Editor and click on a skill node to select it

2. Click "Find Scene Instructions" Button

   In the Inspector, you'll see a green button if instructions exist, or a gray button to create new ones

3. Create Instructions (if needed)

   If no instructions exist, the button offers to create a new SkillInstructions GameObject automatically

4. Configure Instructions

   Enable the event checkboxes (On Unlocked, On Activated, On Upgrade) and add your Game Creator Instructions

Events & Custom Actions

React to skill events with Game Creator instructions for visual effects, sounds, and gameplay logic.

Available Events

Example: Fireball Skill

Skill: "Fireball"
├── Type: Active
├── On Skill Unlocked:
│   ├── Show Message: "Fireball Learned!"
│   └── Play Audio: magic_learn.wav
│
└── On Skill Activated:
    ├── Play Animation: cast_spell
    ├── Wait: 0.3 seconds
    ├── Spawn Prefab: fireball_projectile
    ├── Wait: 0.5 seconds
    └── Condition: If target hit
        └── Reduce Health: 50 damage

Best Practices