Migration Guide

Upgrading existing projects to Simple Attribute Forge Ultimate

Migration Overview

This guide covers migrating from the base Simple Attribute Forge system to the Ultimate version, including handling breaking changes from base system updates and upgrading existing projects.

Migration Scenarios:

Fresh install of Ultimate on existing base system
Upgrading base system with existing Ultimate installation
Moving existing formulas to Pro system
Handling breaking changes from base system updates

Breaking Changes from Base System Updates

BREAKING: value property deprecated

The value property has been replaced with the three-tier value system.

// Old code (deprecated):
float health = healthAttribute.value;

// New code:
float health = healthAttribute.totalValue;

Impact: All direct .value access must be updated to use the appropriate tier (baseValue, formulaBonus, modifierBonus, or totalValue).

BREAKING: Three-tier value system

Attributes now have three distinct value components instead of a single value:

public class SimpleRuntimeAttribute
{
    public float baseValue;      // Core attribute value (equipment, permanent upgrades)
    public float formulaBonus;   // Calculated by Pro formula system (read-only)
    public float modifierBonus;  // Temporary effects (buffs, debuffs)
    public float totalValue;     // baseValue + formulaBonus + modifierBonus (read-only)
}

Property	Purpose	Modified By	When to Use
`baseValue`	Core attribute value	Equipment, level-ups, permanent upgrades	Setting permanent changes
`formulaBonus`	Formula-calculated bonuses	Ultimate influence system only	Read-only in your code
`modifierBonus`	Temporary modifiers	Buffs, debuffs, temporary effects	Temporary effect systems
`totalValue`	Final computed value	System automatically calculated	Gameplay calculations

BREAKING: ISimpleAttributeDataSource interface requirement

All attribute system components must now implement the ISimpleAttributeDataSource interface for Ultimate compatibility.

// Generated attribute classes now implement:
public class CharacterAttributes : MonoBehaviour, ISimpleAttributeDataSource
{
    // Interface provides standardized access methods
    public SimpleRuntimeAttribute GetAttribute(string attributeName);
    public bool HasAttribute(string attributeName);
    public IEnumerable GetAllAttributes();
}

Solution: Regenerate your attribute classes using the latest Attribute Data Wizard to automatically implement this interface.

BREAKING: Regeneration system changes

Regeneration coroutines are no longer managed internally. Components must handle regeneration events.

// Old automatic regeneration (removed):
// System automatically managed regeneration coroutines

// New event-based regeneration:
void Start()
{
    healthAttribute.OnShouldStartRegeneration += StartHealthRegen;
    healthAttribute.OnShouldStopRegeneration += StopHealthRegen;
    manaAttribute.OnShouldStartRegeneration += StartManaRegen;
    manaAttribute.OnShouldStopRegeneration += StopManaRegen;
}

void StartHealthRegen(SimpleRuntimeAttribute attr)
{
    StartCoroutine(RegenerateHealth(attr));
}

void StopHealthRegen(SimpleRuntimeAttribute attr)
{
    StopCoroutine(RegenerateHealth(attr));
}

BREAKING: Scene reference reset

Regenerating attribute classes breaks existing scene references due to class recreation.

Impact: All GameObjects with attribute components will need to be reassigned after regeneration.

Step-by-Step Migration Process

1 Backup Your Project

Create complete project backup or commit current state to version control
Export attribute configuration JSON from base system wizard
Document any custom scripts that reference attribute values
Screenshot current scene component assignments

2 Install Ultimate System

Import Simple Attribute Forge Ultimate package
Verify no compilation errors after import
Check that Influence Wizard appears in Window menu

3 Regenerate Base Attribute System

Required Steps:
Open Window → Simple Attribute Forge → Attribute Data Wizard
Load your existing attribute configuration
Click "Generate" to recreate classes with ISimpleAttributeDataSource
Wait for Unity compilation to complete

Critical: This step breaks all existing scene references. You'll need to reassign attribute components in all scenes.

4 Fix Scene References

Find all GameObjects with missing attribute components (pink/broken references)
Remove old broken components
Add the newly generated attribute components
Restore attribute values from backup/screenshots

5 Update Code References

// Use Find & Replace in your IDE to update code:

Find: .value
Replace: .totalValue

Find: GetValue()
Replace: GetCurrentValue()

Find: SetValue(
Replace: baseValue =

Find: ModifyValue(
Replace: ModifyCurrentValue(  // For Vitals only

6 Setup Ultimate Influence System

Open Window → Simple Attribute Forge → Influence Wizard
Select your regenerated AttributeData asset in Setup tab
Create formulas in Formulas tab
Configure system settings in Configuration tab
Generate orchestrator in Generate tab

7 Integrate Orchestrator

Add generated orchestrator component to GameObjects with attributes
Assign Attribute System reference to your attribute component
Verify formula assets are assigned correctly
Test in Play Mode to confirm formulas execute

8 Update Save/Load Systems

// Old save system (single value):
PlayerPrefs.SetFloat("player_health", health.value);
PlayerPrefs.SetFloat("player_mana", mana.value);

// New save system (base + current for Vitals):
PlayerPrefs.SetFloat("player_health_base", health.baseValue);
PlayerPrefs.SetFloat("player_health_current", health.currentValue);
PlayerPrefs.SetFloat("player_mana_base", mana.baseValue);
PlayerPrefs.SetFloat("player_mana_current", mana.currentValue);
PlayerPrefs.SetFloat("player_strength_base", strength.baseValue);

// Loading:
health.baseValue = PlayerPrefs.GetFloat("player_health_base");
health.currentValue = PlayerPrefs.GetFloat("player_health_current");
// ... load other attributes ...
orchestrator.RecalculateAll(); // Recalculate formulas after loading

9 Test and Validate

Test all gameplay systems that use attributes
Verify UI displays show correct values
Check that formulas calculate as expected
Test save/load functionality
Verify regeneration events work correctly

Code Migration Examples

Combat System Migration

Before Migration:

public void TakeDamage(float amount)
{
    health.value -= amount;
    
    if (health.value <= 0)
    {
        Die();
    }
    
    // Update UI
    healthBar.fillAmount = health.value / health.maxValue;
}

After Migration:

public void TakeDamage(float amount)
{
    // For Vitals, modify currentValue
    health.ModifyCurrentValue(-amount);
    
    if (health.currentValue <= 0)
    {
        Die();
    }
    
    // Update UI - totalValue includes all bonuses
    healthBar.fillAmount = health.currentValue / health.totalValue;
}

Buff System Migration

Before Migration:

public void ApplyStrengthBuff(float bonus, float duration)
{
    // Directly modify attribute value
    strength.value += bonus;
    
    // Schedule removal
    StartCoroutine(RemoveBuffAfter(bonus, duration));
}

IEnumerator RemoveBuffAfter(float bonus, float duration)
{
    yield return new WaitForSeconds(duration);
    strength.value -= bonus;
}

After Migration:

public void ApplyStrengthBuff(float bonus, float duration)
{
    // Use modifierBonus for temporary effects
    strength.modifierBonus += bonus;
    
    // Formulas automatically recalculate with new totalValue
    // Schedule removal
    StartCoroutine(RemoveBuffAfter(bonus, duration));
}

IEnumerator RemoveBuffAfter(float bonus, float duration)
{
    yield return new WaitForSeconds(duration);
    strength.modifierBonus -= bonus;
    // Formulas automatically recalculate when modifierBonus changes
}

UI System Migration

Before Migration:

void UpdateUI()
{
    // Simple value display
    healthText.text = $"{health.value:F0}/{health.maxValue:F0}";
    strengthText.text = $"STR: {strength.value:F0}";
    damageText.text = $"DMG: {CalculateDamage():F0}";
}

After Migration:

void UpdateUI()
{
    // Show current/total for Vitals
    healthText.text = $"{health.currentValue:F0}/{health.totalValue:F0}";
    
    // Show total value with bonus breakdown
    strengthText.text = $"STR: {strength.totalValue:F0}";
    if (strength.formulaBonus != 0)
    {
        strengthBonusText.text = $"(+{strength.formulaBonus:F0})";
    }
    
    // Damage automatically calculated by formulas
    damageText.text = $"DMG: {damage.totalValue:F0}";
}

Equipment System Migration

Before Migration:

public void EquipWeapon(WeaponData weapon)
{
    // Direct stat modification
    strength.value += weapon.strengthBonus;
    damage.value += weapon.damageBonus;
    
    currentWeapon = weapon;
}

After Migration:

public void EquipWeapon(WeaponData weapon)
{
    // Modify base values for permanent equipment bonuses
    strength.baseValue += weapon.strengthBonus;
    damage.baseValue += weapon.damageBonus;
    
    // Formulas automatically recalculate totalValue
    // No need to manually update dependent calculations
    
    currentWeapon = weapon;
}

Ultimate System Integration

Creating Your First Formula

After completing base system migration, add Ultimate formulas to enhance your attribute relationships:

1 Open Influence Wizard

Window → Simple Attribute Forge → Influence Wizard

2 Connect to Attribute System

Setup Tab Configuration:
• Select your AttributeData asset (from regenerated base system)
• Verify all attributes appear in the Available Attributes list
• Confirm no errors or warnings

3 Create Basic Formula

Example: Strength affects Damage
• Add Formula: "StrengthDamage"
• Target Attribute: "Damage"
• Flat Row: Strength Add 2.0
• Test in preview panel

Result: Each STR point adds 2 to damage.totalValue

4 Generate and Test

Generate orchestrator in Generate tab
Add orchestrator component to GameObject with attributes
Assign Attribute System reference
Test in Play Mode - damage.formulaBonus should update when strength changes

Common Migration Issues

Scene Reference Problems

Broken Component References:

Pink/missing component references after regeneration
Scripts that can't find attribute components
UI systems that no longer update

Solutions:

Remove broken components and re-add regenerated versions
Update GetComponent calls to use new class names
Reassign UI references in inspector

Value Access Issues

Compilation Errors:

'value' property no longer exists
Direct value assignment fails
Math operations on deprecated properties

Solutions:

Replace .value with .totalValue for reading
Replace .value assignments with .baseValue assignments
Use ModifyCurrentValue() for Vitals

Regeneration System Issues

Missing Regeneration:

Vitals no longer regenerate automatically
Console errors about missing coroutine management

Solutions:

Implement regeneration event handlers
Create coroutines for regeneration logic
Test regeneration start/stop behavior

Formula Integration Problems

Formulas Not Working:

formulaBonus always shows 0
totalValue equals baseValue only
No automatic recalculation

Solutions:

Verify orchestrator component is added
Check Attribute System reference is assigned
Ensure formula assets are generated and assigned
Test with debugMode enabled

Migration Validation

Compatibility Checker Script

Add this script to verify your migration was successful:

using UnityEngine;
using SimpleAttributeForge;

public class MigrationValidator : MonoBehaviour
{
    [ContextMenu("Validate Migration")]
    void ValidateMigration()
    {
        Debug.Log("=== Migration Validation Report ===");
        
        // Check for ISimpleAttributeDataSource implementation
        var attributeComponent = GetComponent();
        if (attributeComponent is ISimpleAttributeDataSource dataSource)
        {
            Debug.Log(" ISimpleAttributeDataSource implemented correctly");
            
            // Test attribute access
            var allAttributes = dataSource.GetAllAttributes();
            Debug.Log($" Found {allAttributes.Count()} attributes");
            
            foreach (var attr in allAttributes)
            {
                Debug.Log($" {attr.name}: base={attr.baseValue:F1}, " +
                         $"formula={attr.formulaBonus:F1}, total={attr.totalValue:F1}");
            }
        }
        else
        {
            Debug.LogError("✗ Component does not implement ISimpleAttributeDataSource");
            Debug.LogError("  → Regenerate attributes with latest base system");
        }
        
        // Check for orchestrator
        var orchestrator = GetComponent();
        var orchestratorType = orchestrator?.GetType();
        if (orchestratorType?.Name.Contains("Influence") == true)
        {
            Debug.Log($" Orchestrator found: {orchestratorType.Name}");
        }
        else
        {
            Debug.LogWarning(" No orchestrator component found");
            Debug.LogWarning("  → Add orchestrator component after generating Pro system");
        }
        
        Debug.Log("=== End Validation Report ===");
    }
}

Formula Testing

// Test formula calculations manually
[ContextMenu("Test Formula System")]
void TestFormulas()
{
    var attributes = GetComponent();
    var orchestrator = GetComponent(); // Your generated orchestrator
    
    // Test base value changes
    var strength = attributes.GetAttribute("Strength");
    float oldStrength = strength.baseValue;
    
    strength.baseValue = 25;
    orchestrator.SendMessage("RecalculateAll"); // Force recalculation
    
    Debug.Log($"STR 25: Damage formulaBonus = {attributes.GetAttribute("Damage").formulaBonus}");
    
    strength.baseValue = 35;
    orchestrator.SendMessage("RecalculateAll");
    
    Debug.Log($"STR 35: Damage formulaBonus = {attributes.GetAttribute("Damage").formulaBonus}");
    
    // Restore original value
    strength.baseValue = oldStrength;
}

Migration Best Practices

Recommended Migration Approach:

Incremental Migration: Migrate one system at a time, test thoroughly
Maintain Compatibility: Keep old save files working during transition
Document Changes: Track all modified scripts and configurations
Test Extensively: Verify all gameplay systems work correctly
Team Communication: Coordinate migration across team members

Value System Guidelines

Value Usage Best Practices:

• baseValue: Permanent character progression (levels, equipment, upgrades)
• modifierBonus: Temporary effects (buffs, debuffs, environmental)
• formulaBonus: Let Pro system manage this automatically
• totalValue: Use for all gameplay calculations and UI display

Never directly modify formulaBonus - it's managed by the influence system.

Performance Considerations

Update Mode: Start with Smart mode, switch to Interval if performance issues arise
Formula Complexity: Begin with simple formulas, add complexity gradually
Caching: Enable caching for systems with many formulas
Debug Mode: Disable in production builds

Team Workflow

Team Migration Strategy:
One team member performs migration on main branch
Export Pro formula configurations to JSON
Share JSON with team for import into their branches
Test merged systems thoroughly before production
Update team documentation with new API patterns

Rollback Plan

If migration encounters critical issues, you can rollback using these steps:

Emergency Rollback Process:

Restore project from backup
Remove Pro package import
Restore original attribute classes
Reassign scene references to original components
Restore original scripts using version control

Partial Rollback: You can remove Pro components while keeping the updated base system by deleting orchestrator components and Pro formula assets.

Migration Completion Checklist

Pre-Migration

☐ Project backup created
☐ Attribute configuration exported
☐ Custom scripts documented
☐ Scene assignments documented

Base System Update

☐ Attributes regenerated with ISimpleAttributeDataSource
☐ Scene references reassigned
☐ Code updated for three-tier value system
☐ Regeneration events implemented

Pro Integration

☐ Influence Wizard connected to AttributeData
☐ Formulas created and tested
☐ Orchestrator generated and integrated
☐ Formula calculations verified in Play Mode

Final Validation

☐ All gameplay systems functional
☐ UI displays correct values
☐ Save/load systems updated
☐ Performance acceptable
☐ No console errors

Version Compatibility

Supported Migration Paths

Base System Versions:
 v1.0 → Ultimate v1.0: Full compatibility
 v1.1 → Ultimate v1.0: Requires regeneration
 v1.2+ → Ultimate v1.0: Three-tier system compatible

Ultimate System Versions:
 Ultimate v1.0 → Ultimate v1.0+: Forward compatible
 Ultimate v1.0+ → Ultimate v1.0: May lose features

Unity Version Requirements

Minimum Requirements:
• Unity 2021.3 LTS or later
• .NET Standard 2.1
• Serialization system v2

Recommended:
• Unity 2022.3 LTS
• Latest .NET framework version

Compatibility Notes: Ultimate system maintains backward compatibility with base system APIs. Existing base system functionality continues to work unchanged.