123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
# 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/`
|