idle/BUFF_MIGRATION.md

Buff System Migration Guide

Overview

This guide walks you through migrating from per-generator buffs to the new global buff system.

Prerequisites

• Backup your existing save file: user://idle_save.json
• Note: This is a breaking change - old saves (v1) will be rejected

Migration Steps

Step 1: Update Buff Resources

Open each buff in res://sandbox/buffs/ and set the target_ids field:

For buffs that should apply to all generators:

• Set target_ids = ["*"]

For buffs that target specific generators:

• Set target_ids = ["generator_id_1", "generator_id_2"]
• Use the same IDs as defined in your generator data files

Example:

# farm_flux.tres
target_ids = ["farm", "forestry"]  # Multi-target buff

# global_boost.tres  
target_ids = ["*"]  # Wildcard - all current and future generators

Step 2: Update Generator Resources

Open each generator in res://sandbox/generators/ and:

1. Remove the buffs array field (or clear it)
2. (Optional) Add expected_buff_ids for documentation purposes

This is safe because generators now query GameState.get_buffs_for_generator() at runtime.

Step 3: Delete Old Save Files

Delete user://idle_save.json to start fresh with the new v2 format.

Note: There is no automatic migration from v1 to v2. Players will need to start new games.

Step 4: Verify Auto-Discovery

The BuffDatabase autoload will automatically load all .tres files from res://sandbox/buffs/ at runtime.

Verify in the output log:

BuffDatabase initialized with N buffs

Step 5: Test Key Scenarios

Run through these test cases:

1. Single-target buff: Buy a buff that targets only one generator

   • Verify only that generator's production increases

2. Multi-target buff: Buy a buff targeting multiple generators

   • Verify all targeted generators' production increases

3. Wildcard buff: Buy a buff with target_ids = ["*"]

   • Verify ALL generators (current and future) get the bonus

4. Goal unlock: Meet a buff unlock goal

   • Verify the buff automatically unlocks and activates

5. Save/Load: Save the game, close, and reopen

   • Verify buff levels and unlock states persist

6. Prestige: Perform a prestige

   • Verify all buff levels reset to 0
   • Verify buff unlock states reset to false

Rollback (If Needed)

If issues arise:

1. Revert all code changes using git
2. Restore old save file from backup
3. Restore buff/generator .tres files to original state
4. Remove BuffDatabase from project.godot autoloads

Checking Your Work

After migration, verify:

• All buffs load automatically at startup
• Buff UI displays correctly for each generator
• Buying a buff level increases the GLOBAL level (not per-generator)
• Multi-target buffs affect all specified generators
• Wildcard buffs affect all generators
• Save files include buff state (version 2)
• Prestige resets all buff levels

Common Issues

Issue: Buff not appearing in UI

Solution: Check that the buff's target_ids includes the generator's ID or uses ["*"]

Issue: Wildcard buffs not applying to new generators

Solution: Ensure new generators call GameState.register_buff() for each buff they should inherit

Issue: Old save won't load

Solution: This is expected - v1 saves are incompatible. Delete user://idle_save.json and start fresh.

Issue: Buff multipliers not stacking

Solution: Verify get_effective_multiplier() is being called and that buff levels > 0

Success Criteria

Migration is complete when:

• ✅ All generators produce correct amounts with active buffs
• ✅ Buff levels are shared globally across all targets
• ✅ Wildcard buffs automatically apply to new generators
• ✅ Save/load preserves buff state correctly
• ✅ Prestige resets all buff levels to 0
• ✅ New buffs can be added by dropping .tres files in res://sandbox/buffs/