# Swarm Scenarios

## Shared setup
- Use at least 2 reusable beehives within `BeehiveRadius` of each other.
- Ensure one target hive can stay below `BeehiveConsideredEmptyBelowPopulation`.
- Keep at least one source hive well above swarm threshold.
- Use warm biome/daytime for temperature-gated scenarios.

### Shared config commands (copy/paste)
```text
/beehives BeehiveRadius 35
/beehives MaxBeePopulation 50000
/beehives BeehiveConsideredEmptyBelowPopulation 500
/beehives PopulationPercentRequirementForSwarm 80
/beehives SwarmPopulationPercentage 0.2
/beehives MaxTemperatureGrowth 10
```

## 1) Open-for-incoming is always below-threshold
- Set hive A population to `499` while threshold is `500`.
- Expected: hive A is eligible as an incoming swarm target.
- Raise hive A to `500` or higher.
- Expected: hive A is no longer eligible.

### Commands
```text
/beehives BeehiveConsideredEmptyBelowPopulation 500
/beehives setPopulation 499
```

## 2) Swarm trigger gates: population, dayhour, pre-swarm progress
- Source hive above required percent (`> 80%` of max by default).
- Test outside 8-12 dayhours.
- Expected: no swarm starts even if pre-swarm is at 100%.
- Test in 8-12 dayhours with pre-swarm at 100% (requires sustained optimal temperature over `PreSwarmDurationHours`).
- Expected: swarm starts.

### Commands
```text
/beehives PopulationPercentRequirementForSwarm 80
/beehives MaxBeePopulation 50000
/beehives setPopulation 45000
```

## 2b) Pre-swarm progress builds at optimal temperature
- Source hive above required percent, cooldown expired.
- Ensure temperature is at or above `MaxTemperatureGrowth`.
- Expected: block info shows "Bees are preparing to swarm" (v1) or progress % (v2+).
- Expected: progress increases from 0 to 100% over `PreSwarmDurationHours` hours.

## 2c) Pre-swarm progress decreases in cold
- Start with some pre-swarm progress built up.
- Drop temperature below `MaxTemperatureGrowth`.
- Expected: pre-swarm progress decreases back toward 0.
- Expected: swarm does not trigger until progress reaches 100% again.

## 2d) Wrench disables swarming
- Right-click a beehive with a wrench.
- Expected: block info shows "Swarming is disabled on this beehive."
- Expected: swarm does not trigger even if all conditions are met.
- Right-click again with wrench.
- Expected: swarming re-enabled and normal swarm behavior resumes.

## 3) BuildingSwarm phase is gradual over 3h
- Trigger swarm from source hive.
- During first ~3 in-game hours, observe source population decreasing and swarm population increasing progressively.
- Expected: transition is gradual, not instant.

## 4) HangingOut phase duration
- After BuildingSwarm finishes, swarm enters `HangingOut`.
- Expected: swarm remains in place for ~5 in-game hours.

## 5) MigratingToNewHive phase is gradual over MigrationPhaseDurationHours
- After target pick, swarm enters `MigratingToNewHive`.
- Expected: population transfers gradually for the full migration duration.
- Expected: swarm block disappears at end of migration.

## 6) Target ranking prefers distance * flowers * frame-factor
- Prepare two eligible target hives:
  - B: closer, fewer flowers, no filled/feed frame.
  - C: slightly farther, more flowers, has filled/feed frame.
- Expected: chosen target matches highest multiplicative score.
- Frame factor for any filled/feed frame should act as `2.0` multiplier.

## 7) Vanilla skep target conversion path
- Place empty vanilla skep (`game:skep-reed-empty-*` or `game:skep-papyrus-empty-*`) in radius.
- Ensure it is registered as valid target by behavior patch.
- Expected: at migration start, empty skep is exchanged to populated skep.

## 8) No-target retry behavior
- Let swarm finish hanging with zero eligible targets.
- Expected: no immediate disperse; retry occurs in next day swarm window (8-12).
- If still no valid target after retry, expected: swarm disperses.

## 9) Spawn placement preference
- Trigger multiple swarm spawns with varied nearby geometry.
- Expected priority:
  1. side-attached on solid-faced wood blocks,
  2. side-attached on other solid-faced blocks,
  3. floor-attached fallback.

## 10) Info text validation
- Beehive info: when source is ready, expected `Ready to swarm` line.
- Swarm block info: expected state + population + eligible target count + hours-until-pick lines.

## 11) Command-assisted deterministic setup
- Use command to quickly shape scenario state.
- Expected: `/beehives setPopulation {int}` updates targeted reusable beehive population immediately.

### Commands
```text
/beehives setPopulation 200
/beehives setPopulation 45000
```

## 12) Unload before swarm window (no missed swarm)
- Make source hive swarm-ready but unload area before 8:00.
- Re-enter area after 8:00 same day.
- Expected: catch-up applies population/honey/feed updates.
- Expected: swarm only starts if simulated timeline crosses valid window while ready.

## 13) Unload during BuildingSwarm phase
- Trigger swarm and unload area while swarm is in `BuildingSwarm`.
- Stay away long enough to skip part or all of the 3h building phase.
- Re-enter area.
- Expected: swarm population is already advanced to the correct catch-up value.
- Expected: source hive population has already lost corresponding bees.

## 14) Unload during HangingOut phase
- Trigger swarm and unload area after `BuildingSwarm` finishes.
- Stay away through part or all of `HangingOut`.
- Re-enter area.
- Expected: swarm resumes in correct post-catch-up state.
- Expected: if hanging duration elapsed and a target exists, migration may already have started or completed.

## 15) Unload during MigratingToNewHive phase
- Trigger migration, then unload area before migration completes.
- Re-enter area after enough time has passed.
- Expected: transferred bee count reflects elapsed offline time.
- Expected: swarm block is gone if migration fully completed.
- Expected: target hive population increased according to migrated amount.

## 16) Full lifecycle while unloaded (start -> finish)
- Make source hive swarm-ready in morning window.
- Unload immediately before/at expected swarm start and stay away for longer than full lifecycle.
- Re-enter area.
- Expected: catch-up simulation spawns swarm at historical time and fast-forwards it.
- Expected: resulting world state matches completed lifecycle outcome (target populated or swarm dispersed).
- Expected: source cooldown is based on simulated swarm start time.

## 17) Retry path while unloaded (no targets first day)
- Ensure no eligible targets when hanging phase ends.
- Unload through first retry day window and re-enter later.
- Expected: retry-day behavior is honored by catch-up.
- Expected: swarm disperses if no valid target remains after retry.

## 18) Debug chat output for unload catch-up
- Enable debug output before running unload scenarios.
- Expected: chat shows catch-up start/end summaries, population deltas, and swarm lifecycle catch-up events.

### Commands
```text
/beehives debugUnload true
/beehives debugUnload false
```

## 19) SwarmPopulationPercentageWhenNoBeehivesAvailable: zero value skips spawn
- Ensure there are no eligible swarm targets in range (no empty beehives or skeps).
- Set `SwarmPopulationPercentageWhenNoBeehivesAvailable` to `0`.
- Trigger swarm conditions on source hive.
- Expected: no swarm block is spawned.
- Expected: cooldown is applied as if the swarm had occurred (`NextSwarmAllowedTotalDays` advances).

### Commands
```text
/beehives SwarmPopulationPercentageWhenNoBeehivesAvailable 0
```

## 20) SwarmPopulationPercentageWhenNoBeehivesAvailable: non-zero value spawns smaller swarm
- Ensure there are no eligible swarm targets in range.
- Set `SwarmPopulationPercentageWhenNoBeehivesAvailable` to a value greater than `0` (e.g., `5`).
- Trigger swarm conditions on source hive.
- Expected: a swarm block is spawned with a planned population equal to `5%` of the source hive population.
- Expected: swarm eventually disperses (no target found).

### Commands
```text
/beehives SwarmPopulationPercentageWhenNoBeehivesAvailable 5
```