# 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:**
```gdscript
# 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/`