feat: scouts: a scout unit that meets the defending scouts and reports troops, resources and buildings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Fabian @ Blax Software 2026-10-29 00:10:49 +01:00
parent 28ee28120b
commit 6e6c12f9b5
8 changed files with 115 additions and 12 deletions

View File

@ -263,7 +263,15 @@ final class Rally
$luck = $combat->luck(mt_rand() / (mt_getrandmax() + 1));
$morale = $combat->morale($defenderPoints, (int) Village::where('player_id', $movement->player_id)->sum('points'));
$night = $combat->night($at);
$battle = $combat->fight($movement->units, $defense, $wall?->level ?? 0, $morale, $luck, $night);
// Scouts meet the defending scouts first and never fight; the rest of the army does.
$isScout = fn (string $unit) => (bool) $config->get("units.$unit.scout", false);
$scouts = array_filter($movement->units, fn (int $n, string $unit) => $isScout($unit), ARRAY_FILTER_USE_BOTH);
$army = array_diff_key($movement->units, $scouts);
$watchers = array_sum(array_filter($defense, fn (int $n, string $unit) => $isScout($unit), ARRAY_FILTER_USE_BOTH));
[$through, $scoutsLost] = $combat->scout(array_sum($scouts), $watchers);
$battle = $army ? $combat->fight($army, $defense, $wall?->level ?? 0, $morale, $luck, $night) : null;
$won = $battle ? $battle->attackerWon : $through;
// Defenders fall in every stack alike, support included.
$defenseLost = [];
@ -272,14 +280,14 @@ final class Rally
if ($stack->home_village_id !== $this->village->id) {
$supporters[$stack->home_village_id] = true;
}
$dead = Battle::dead([$stack->unit => $stack->count], $battle->defenseLoss)[$stack->unit];
$dead = Battle::dead([$stack->unit => $stack->count], $battle?->defenseLoss ?? 0.0)[$stack->unit];
$defenseLost[$stack->unit] = ($defenseLost[$stack->unit] ?? 0) + $dead;
$stack->count -= $dead;
$stack->count > 0 ? $stack->save() : $stack->delete();
}
$this->village->setRelation('troops', $this->village->troops->filter(fn (UnitStack $s) => $s->count > 0)->values());
if (isset($defense['militia'])) {
$defenseLost['militia'] = Battle::dead(['militia' => $defense['militia']], $battle->defenseLoss)['militia'];
$defenseLost['militia'] = Battle::dead(['militia' => $defense['militia']], $battle?->defenseLoss ?? 0.0)['militia'];
$this->village->militia -= $defenseLost['militia'];
if ($this->village->militia <= 0) {
Military::of($this->village, $this->sim)->endLevy($at);
@ -287,11 +295,14 @@ final class Rally
}
$damaged = false;
if ($wall && $battle->wallAfter < $wall->level) {
if ($wall && $battle && $battle->wallAfter < $wall->level) {
$this->damage($wall, $battle->wallAfter, $at);
$damaged = true;
}
$attackLost = Battle::dead($movement->units, $battle->attackLoss);
$attackLost = [
...($battle ? Battle::dead($army, $battle->attackLoss) : []),
...Battle::dead($scouts, $scouts ? $scoutsLost / array_sum($scouts) : 0.0),
];
$survivors = [];
foreach ($movement->units as $unit => $count) {
if ($count > $attackLost[$unit]) {
@ -300,7 +311,7 @@ final class Rally
}
$hit = null;
if ($battle->attackerWon && ($survivors['catapult'] ?? 0) > 0 && $movement->catapult_target) {
if ($battle?->attackerWon && ($survivors['catapult'] ?? 0) > 0 && $movement->catapult_target) {
$building = $this->village->buildings->where('type', $movement->catapult_target)->sortByDesc('level')->first();
if ($building) {
$after = $combat->siege('catapult', $building->level, $survivors['catapult']);
@ -314,7 +325,7 @@ final class Rally
$loot = ['wood' => 0, 'clay' => 0, 'iron' => 0];
$capacity = 0;
if ($battle->attackerWon) {
if ($battle?->attackerWon) {
$capacity = (new LootCalculator($config))->capacity($survivors);
$stock = ['wood' => $this->village->wood, 'clay' => $this->village->clay, 'iron' => $this->village->iron];
$loot = LootCalculator::take($stock, $this->hidden(), $capacity);
@ -327,20 +338,30 @@ final class Rally
}
$origin = Village::with('player')->find($movement->origin_id);
$scouted = $through && $scoutsLost < array_sum($scouts);
$report = [
'won' => $battle->attackerWon,
'won' => $won,
'luck' => round($luck * 100, 1),
'morale' => (int) round($morale * 100),
'night' => $night > 1,
'attacker' => ['village' => self::summary($origin), 'units' => $movement->units, 'lost' => $attackLost],
'defender' => ['village' => self::summary($this->village), 'units' => $defense, 'lost' => $defenseLost],
'wall' => $wall ? ['before' => $battle->wallBefore, 'after' => $wall->level] : null,
'wall' => $wall && $battle ? ['before' => $battle->wallBefore, 'after' => $wall->level] : null,
'building' => $hit,
'loot' => $loot,
'capacity' => $capacity,
// What scouts that got through saw, after the battle.
'scouting' => $scouts ? [
'sent' => array_sum($scouts),
'lost' => $scoutsLost,
'through' => $scouted,
'resources' => $scouted ? array_map(fn (float $n) => (int) floor($n), ['wood' => $this->village->wood, 'clay' => $this->village->clay, 'iron' => $this->village->iron]) : null,
'buildings' => $scouted ? $this->village->buildings->groupBy('type')->map(fn ($b) => $b->pluck('level')->sortDesc()->values()->all())->all() : null,
] : null,
];
// An attacker with no survivors learns nothing about the defence.
$seen = $survivors ? $report : ['defender' => ['village' => $report['defender']['village'], 'units' => null, 'lost' => null], 'wall' => null] + $report;
// An attacker learns about the defence from survivors of the battle or scouts that got through.
$informed = ($battle && array_diff_key($survivors, $scouts)) || $scouted;
$seen = $informed ? $report : ['defender' => ['village' => $report['defender']['village'], 'units' => null, 'lost' => null], 'wall' => null] + $report;
Report::write($movement->player_id, Report::ATTACK, $seen, $at);
Report::write($this->village->player_id, Report::DEFENSE, $report, $at);
foreach (Village::whereIn('id', array_keys($supporters))->get() as $home) {

View File

@ -42,6 +42,27 @@ final class CombatResolver
return new Battle(false, 1.0, ($attackPower / $defensePower) ** $exponent, $wall, $wallAfter, $attackPower, $defensePower);
}
/**
* Attacking scouts against the scouts in the village. They get through when they
* outnumber the defence (scouting.defense × defenders) and lose (defence / attack)^1.5
* of themselves; otherwise all of them die. Defending scouts never die here.
*
* @return array{0: bool, 1: int} whether they got through, and how many died
*/
public function scout(int $attackers, int $defenders): array
{
if ($attackers <= 0) {
return [false, 0];
}
$defense = $defenders * (float) $this->config->get('combat.scouting.defense', 1.0);
if ($attackers <= $defense) {
return [false, $attackers];
}
$loss = ($defense / $attackers) ** (float) $this->config->get('combat.loss_exponent', 1.5);
return [true, min($attackers, (int) round($attackers * $loss))];
}
/**
* The level a building is left at after $count rams or catapults hit it. Each level
* L down needs base × factor^(L − 1) of them; nothing drops below level 1.

View File

@ -27,6 +27,11 @@ return [
// Defence × factor while the defender's clock is between start and end (hours).
'night' => ['enabled' => false, 'start' => 0, 'end' => 8, 'factor' => 2.0, 'timezone' => 'Europe/Berlin'],
// Scouts meet scouts before the battle: the attacking ones get through when they
// outnumber defence × the defending scouts, losing (defence / attack)^loss_exponent of
// themselves; otherwise all of them die. Defending scouts never die in this.
'scouting' => ['defense' => 1.0],
// Levied villagers defend with these values per head.
'militia' => ['defense' => ['infantry' => 5, 'cavalry' => 5, 'archer' => 5]],

View File

@ -42,6 +42,21 @@ return [
'carry' => 10,
'requires' => ['barracks' => 3],
],
// Scouts don't fight: they meet the defending scouts first, and if enough get through,
// the report shows the village's troops, resources and buildings (combat.scouting).
'scout' => [
'building' => 'stable',
'cost' => ['wood' => 50, 'clay' => 50, 'iron' => 20],
'upkeep' => 2,
'build_time' => 900,
'attack' => 0,
'defense' => ['infantry' => 0, 'cavalry' => 0, 'archer' => 0],
'class' => 'cavalry',
'speed' => 9,
'carry' => 0,
'scout' => true,
'requires' => [],
],
'light_cavalry' => [
'building' => 'stable',
'cost' => ['wood' => 125, 'clay' => 100, 'iron' => 250],

View File

@ -219,4 +219,5 @@ Combat uses the TW model, in `CombatResolver` (pure, tested with fixed luck) and
- The attack is multiplied by morale and (1 + luck). Luck is drawn evenly from ±`combat.luck` (25%) with the movement's seed, so a replayed event fights the same battle. Morale is `min(1, 0.3 + 3 × defender points / attacker points)` and always 1 against barbarians. Worlds with a night bonus multiply the defence at night.
- The winner loses `(loser / winner)^1.5` of every unit, rounded per stack; the loser loses everything. Dead militia shrink the levy.
- After a won battle, surviving catapults hit the highest instance of the chosen type (headquarters by default) by the same siege rule. A damaged building's queued orders are cancelled with a full refund, since their levels no longer fit.
- Scouts (units with `scout: true`) never fight. They meet the scouts in the village first: they get through when they outnumber `combat.scouting.defense` × the defending scouts, losing `(defence / attack)^1.5` of themselves; otherwise all of them die, and defending scouts never die in this. Scouts that get through add the village's resources and building levels, after the battle, to the attacker's report. Scouts alone cause no battle; defending scouts die with the village's other defenders when a battle is lost.
- `LootCalculator`: survivors carry `carry` per unit. They take wood, clay and iron evenly, above what the hiding places protect (`hides` per resource; instances add up). Food is not looted.

View File

@ -226,3 +226,34 @@ it('sends hungry support home before own soldiers desert', function () {
->and($state['starvation']['since'])->toBeNull()
->and(shown($home)['movements'][0])->toMatchArray(['type' => 'return', 'units' => ['spear' => 30]]);
});
it('scouts a village without a fight, and loses every scout against more defending ones', function () {
$attacker = rallied(startVillage(), ['scout' => 10]);
$defender = startVillage();
$defender->troops()->create(['home_village_id' => $defender->id, 'unit' => 'sword', 'count' => 20]);
worldRules($attacker, ['combat' => ['beginner_protection' => 0]]);
send($attacker, $defender, ['scout' => 5]);
$this->travel(1)->days();
$this->artisan('game:events --once')->assertSuccessful();
$report = Report::where('player_id', $attacker->player_id)->sole()->payload;
expect($report['won'])->toBeTrue()
->and($report['defender']['units'])->toBe(['sword' => 20])
->and($report['defender']['lost'])->toBe(['sword' => 0])
->and($report['scouting'])->toMatchArray(['sent' => 5, 'lost' => 0, 'through' => true])
->and($report['scouting']['buildings'])->toMatchArray(['headquarters' => [1], 'storage' => [1], 'farm' => [1]])
->and($report['scouting']['resources']['wood'])->toBeGreaterThan(500)
->and((array) shown($attacker)['troops'])->toBe(['scout' => 10])
->and((array) shown($defender)['troops'])->toBe(['sword' => 20]);
$defender->troops()->create(['home_village_id' => $defender->id, 'unit' => 'scout', 'count' => 8]);
send($attacker, $defender, ['scout' => 5]);
$this->travel(1)->days();
$this->artisan('game:events --once')->assertSuccessful();
$report = Report::where('player_id', $attacker->player_id)->latest('id')->first()->payload;
expect($report['won'])->toBeFalse()
->and($report['scouting'])->toMatchArray(['lost' => 5, 'through' => false, 'resources' => null])
->and($report['defender']['units'])->toBeNull()
->and((array) shown($attacker)['troops'])->toBe(['scout' => 5])
->and((array) shown($defender)['troops'])->toBe(['sword' => 20, 'scout' => 8]);
});

View File

@ -90,3 +90,12 @@ it('loots evenly and lets the other resources make up for a short one', function
it('carries what the survivors can carry', function () {
expect((new LootCalculator(gameConfig()))->capacity(['spear' => 10, 'light_cavalry' => 2, 'ram' => 3]))->toBe(250 + 160);
});
it('lets scouts through when they outnumber the defending ones', function () {
$combat = new CombatResolver(gameConfig());
expect($combat->scout(10, 0))->toBe([true, 0])
->and($combat->scout(10, 4))->toBe([true, (int) round(10 * 0.4 ** 1.5)])
->and($combat->scout(5, 5))->toBe([false, 5])
->and($combat->scout(0, 3))->toBe([false, 0]);
});

View File

@ -7,7 +7,7 @@ it('knows where each unit is trained', function () {
$units = new UnitRules(gameConfig());
expect($units->trainedAt('barracks'))->toBe(['spear', 'sword', 'archer'])
->and($units->trainedAt('stable'))->toBe(['light_cavalry', 'heavy_cavalry'])
->and($units->trainedAt('stable'))->toBe(['scout', 'light_cavalry', 'heavy_cavalry'])
->and($units->trainedAt('academy'))->toBe(['nobleman'])
->and($units->trainedAt('farm'))->toBe([]);
});