2026-10-28 18:17:34 +00:00
< ? php
namespace App\Game ;
use App\Game\Buildings\BuildingRules ;
2026-10-28 20:39:48 +00:00
use App\Game\Military\UnitRules ;
2026-10-28 18:17:34 +00:00
/**
* Proves a world config has no locks ( architecture . md , " No locks " ) .
* Every check returns problems as sentences ; an empty list means the config is safe .
*/
final class ConfigLint
{
/** @return list<string> */
public static function check ( WorldConfig $config ) : array
{
$rules = new BuildingRules ( $config );
return [
... self :: startVillageFits ( $config , $rules ),
2026-10-28 20:28:16 +00:00
... self :: foodCanBeStored ( $config ),
2026-10-28 18:17:34 +00:00
... self :: farmsFeedTheirWorkers ( $config , $rules ),
... self :: costsFitStorage ( $config , $rules ),
... self :: requirementsReachable ( $config , $rules ),
2026-10-28 20:39:48 +00:00
... self :: unitsTrainable ( $config , $rules ),
2026-10-28 21:03:33 +00:00
... self :: timersRun ( $config ),
2026-10-29 09:05:55 +00:00
... self :: questsReachable ( $config , $rules ),
2026-10-29 15:02:49 +00:00
... self :: garrisonsRegroup ( $config ),
2026-10-29 15:07:54 +00:00
... self :: raidsPause ( $config ),
2026-10-28 18:17:34 +00:00
];
}
2026-10-29 09:05:55 +00:00
/** Counter keys the actions bump (App\Engine\Quests::bump), besides recruited.<unit>. */
public const QUEST_COUNTERS = [
'attacks.sent' , 'attacks.barbarian' , 'support.sent' , 'scouts.sent' , 'village.renamed' ,
'priority.set' , 'levy.called' , 'map.viewed' , 'reports.read' ,
];
/**
* Every quest must be completable , or its line stops there for good : known buildings
* at levels that exist , instances that fit the largest village , counters some action
* bumps , and each key once .
*/
private static function questsReachable ( WorldConfig $config , BuildingRules $rules ) : array
{
$units = ( new UnitRules ( $config )) -> units ();
$start = $rules -> spaceUsed ( $config -> get ( 'world.village.start_buildings' , []));
$hqMax = $config -> hasBuilding ( 'headquarters' ) ? $rules -> maxLevel ( 'headquarters' ) : 1 ;
$spaceMax = $rules -> spaceMax (( int ) $config -> get ( 'world.village.space' ), $hqMax );
$seen = [];
$problems = [];
foreach ( $config -> get ( 'quests.lines' , []) as $line => $quests ) {
foreach ( $quests as $key => $quest ) {
if ( isset ( $seen [ $key ])) {
$problems [] = " Quest [ $key ] appears twice. " ;
}
$seen [ $key ] = true ;
foreach ( $quest [ 'goals' ] as [ $kind , $subject , $need ]) {
$problem = match ( true ) {
$kind === 'counter' => in_array ( $subject , self :: QUEST_COUNTERS , true )
|| ( str_starts_with ( $subject , 'recruited.' ) && in_array ( substr ( $subject , 10 ), $units , true ))
? null : " counts [ $subject ], which no action bumps " ,
! in_array ( $kind , [ 'building' , 'instances' ], true ) => " has an unknown goal [ $kind ] " ,
! $config -> hasBuilding ( $subject ) => " needs unknown building [ $subject ] " ,
$kind === 'building' && $need > $rules -> maxLevel ( $subject ) => " needs [ $subject ] level $need , above its maximum " ,
$kind === 'instances' && (( $rules -> maxPerVillage ( $subject ) ? ? $need ) < $need || $start + $need * $rules -> space ( $subject ) > $spaceMax ) => " needs $need [ $subject ] in one village, which never fit " ,
default => null ,
};
if ( $problem ) {
$problems [] = " Quest [ $line . $key ] $problem . " ;
}
}
}
}
return $problems ;
}
2026-10-29 15:02:49 +00:00
/**
* Barbarian garrisons field real units , regroup in finite steps , and eat less than
* their village ' s villagers leave over , so they never starve it .
*/
private static function garrisonsRegroup ( WorldConfig $config ) : array
{
$garrison = $config -> get ( 'world.map.barbarians.garrison' );
if ( ! $garrison ) {
return [];
}
$units = ( new UnitRules ( $config )) -> units ();
$problems = [];
foreach ( $garrison [ 'profiles' ] ? ? [] as $profile => $shares ) {
foreach ( $shares as $unit => $share ) {
if ( ! in_array ( $unit , $units , true ) || $share <= 0 ) {
$problems [] = " Garrison profile [ $profile ] fields [ $unit ], which is not a unit with a share above 0. " ;
}
}
}
if (( $garrison [ 'regroup' ][ 'every_hours' ] ? ? 0 ) <= 0 || ( $garrison [ 'regroup' ][ 'share' ] ? ? 0 ) <= 0 ) {
$problems [] = 'Barbarian garrisons must regroup: [regroup.every_hours] and [regroup.share] above 0.' ;
}
if (( $garrison [ 'max_food_share' ] ? ? 0 ) >= $config -> get ( 'economy.villager_share' , 0.8 )) {
$problems [] = '[garrison.max_food_share] must stay below [economy.villager_share], or a garrison starves its village.' ;
}
return $problems ;
}
2026-10-29 15:07:54 +00:00
/**
* Raids come apart in time , with a warning , from camps in range , in a travel mode
* that exists , and a camp beaten down to nothing sends no band .
*/
private static function raidsPause ( WorldConfig $config ) : array
{
if ( ! $config -> get ( 'raids.enabled' , false )) {
return [];
}
$problems = [];
[ $min , $max ] = $config -> get ( 'raids.every_hours' , [ 0 , 0 ]) + [ 0 , 0 ];
if ( $min <= 0 || $max < $min ) {
$problems [] = '[raids.every_hours] must be two hours above 0, the smaller first, so a village gets time between raids.' ;
}
if ( $config -> get ( 'raids.gather_hours' , 0 ) < 0 || $config -> get ( 'raids.range' , 0 ) <= 0 ) {
$problems [] = '[raids.gather_hours] cannot be negative and [raids.range] must be above 0.' ;
}
$scatter = $config -> get ( 'raids.scatter_below' , 0 );
if ( $scatter <= 0 || $scatter > 1 ) {
$problems [] = '[raids.scatter_below] must be above 0 and at most 1, or beating the camp would not stop its raid.' ;
}
if ( ! $config -> get ( 'movement.modes.' . $config -> get ( 'raids.mode' , 'normal' ))) {
$problems [] = '[raids.mode] is not a travel mode.' ;
}
return $problems ;
}
2026-10-28 21:03:33 +00:00
/** A levy has to end and desertion waves have to come apart in time, or the village stays stuck. */
private static function timersRun ( WorldConfig $config ) : array
{
$problems = [];
foreach ([ 'economy.levy.duration' , 'economy.starvation.wave_every' ] as $key ) {
if ( $config -> get ( $key , 1 ) <= 0 ) {
$problems [] = " [ $key ] must be more than 0 seconds. " ;
}
}
if ( $config -> get ( 'economy.starvation.grace' , 0 ) < 0 ) {
$problems [] = '[economy.starvation.grace] cannot be negative.' ;
}
return $problems ;
}
2026-10-28 18:45:02 +00:00
/**
* The start buildings must exist and fit the building space together , and every
* type must fit next to them , or it could never be built .
*/
2026-10-28 18:17:34 +00:00
private static function startVillageFits ( WorldConfig $config , BuildingRules $rules ) : array
{
2026-10-28 21:26:25 +00:00
// The headquarters starts at level 1, so the start village has the base space.
2026-10-28 18:45:02 +00:00
$max = $config -> get ( 'world.village.space' );
2026-10-28 21:16:45 +00:00
if ( $config -> get ( 'world.village.space_per_hq_level' , 0 ) < 0 ) {
return [ '[world.village.space_per_hq_level] cannot be negative, or upgrading the headquarters would squeeze the village.' ];
}
2026-10-28 18:45:02 +00:00
$start = $config -> get ( 'world.village.start_buildings' , []);
2026-10-28 18:17:34 +00:00
$problems = [];
2026-10-28 18:45:02 +00:00
foreach ( $start as $type ) {
2026-10-28 18:17:34 +00:00
if ( ! $config -> hasBuilding ( $type )) {
$problems [] = " Start building [ $type ] is not a building type. " ;
}
2026-10-28 18:45:02 +00:00
}
if ( $problems ) {
return $problems ;
}
2026-10-28 18:17:34 +00:00
2026-10-28 18:45:02 +00:00
$used = $rules -> spaceUsed ( $start );
if ( $used > $max ) {
return [ " The start buildings take $used building space, more than the village's $max . " ];
}
foreach ( $config -> buildingTypes () as $type ) {
if ( $used + $rules -> space ( $type ) > $max ) {
$problems [] = " [ $type ] does not fit next to the start buildings. " ;
2026-10-28 18:17:34 +00:00
}
}
return $problems ;
}
/** Capacity is never 0, and each farm level's workers eat less than it makes. */
2026-10-28 20:28:16 +00:00
/** Villagers must leave a surplus, or food never builds up and any soldier starves the village. */
private static function foodCanBeStored ( WorldConfig $config ) : array
{
$share = $config -> get ( 'economy.villager_share' , 0.8 );
return $share > 0 && $share < 1
? []
: [ " economy.villager_share must be between 0 and 1 (is $share ), so farms leave a surplus. " ];
}
2026-10-28 18:17:34 +00:00
private static function farmsFeedTheirWorkers ( WorldConfig $config , BuildingRules $rules ) : array
{
$problems = [];
$perVillager = $config -> get ( 'economy.upkeep.villager' , 1 );
foreach ( $config -> buildingTypes () as $type ) {
2026-10-28 21:26:25 +00:00
if (( $rules -> output ( $type , 1 )[ 'resource' ] ? ? null ) !== 'food' ) {
2026-10-28 18:17:34 +00:00
continue ;
}
2026-10-28 21:26:25 +00:00
for ( $level = 1 ; $level <= $rules -> maxLevel ( $type ); $level ++ ) {
2026-10-28 18:17:34 +00:00
$output = $rules -> output ( $type , $level )[ 'per_hour' ];
if ( $output <= 0 || $rules -> workers ( $type , $level ) * $perVillager >= $output ) {
$problems [] = " [ $type ] level $level feeds fewer people than it needs as workers. " ;
}
}
}
return $problems ;
}
/**
* Every level 's cost fits one storage at max level, and storage' s next level
* always fits what its current level holds .
*/
private static function costsFitStorage ( WorldConfig $config , BuildingRules $rules ) : array
{
2026-10-28 21:26:25 +00:00
$storages = array_filter ( $config -> buildingTypes (), fn ( string $t ) => $rules -> capacity ( $t , 1 ) > 0 );
2026-10-28 18:17:34 +00:00
if ( ! $storages ) {
return [ 'No building type provides storage.' ];
}
$problems = [];
$maxCap = max ( array_map ( fn ( string $t ) => $rules -> capacity ( $t , $rules -> maxLevel ( $t )), $storages ));
foreach ( $config -> buildingTypes () as $type ) {
2026-10-28 21:26:25 +00:00
for ( $level = 1 ; $level <= $rules -> maxLevel ( $type ); $level ++ ) {
2026-10-28 18:17:34 +00:00
if ( max ( $rules -> cost ( $type , $level )) > $maxCap ) {
$problems [] = " [ $type ] level $level costs more than the largest storage holds. " ;
}
}
}
foreach ( $storages as $type ) {
2026-10-28 21:26:25 +00:00
for ( $level = 1 ; $level < $rules -> maxLevel ( $type ); $level ++ ) {
2026-10-28 18:17:34 +00:00
if ( max ( $rules -> cost ( $type , $level + 1 )) > $rules -> capacity ( $type , $level )) {
$problems [] = " [ $type ] level " . ( $level + 1 ) . " costs more than level $level holds. " ;
}
}
}
return $problems ;
}
/** Requirements name real types and levels, and have no cycles. */
2026-10-28 20:39:48 +00:00
/** Every unit has a real building to train at, reachable requirements, and a cost storage can hold. */
private static function unitsTrainable ( WorldConfig $config , BuildingRules $rules ) : array
{
$units = new UnitRules ( $config );
$maxCap = max ( array_map ( fn ( string $t ) => $rules -> capacity ( $t , $rules -> maxLevel ( $t )), $config -> buildingTypes ()));
$problems = [];
foreach ( $units -> units () as $unit ) {
if ( ! $config -> hasBuilding ( $units -> building ( $unit ))) {
$problems [] = " [ $unit ] is trained at unknown building [ { $units -> building ( $unit ) } ]. " ;
}
foreach ( $units -> requires ( $unit ) as $type => $level ) {
if ( ! $config -> hasBuilding ( $type ) || $level > $rules -> maxLevel ( $type )) {
$problems [] = " [ $unit ] requires [ $type ] level $level , which can't be built. " ;
}
}
if ( max ( $units -> cost ( $unit )) > $maxCap ) {
$problems [] = " [ $unit ] costs more than the largest storage holds. " ;
}
if ( $units -> upkeep ( $unit ) <= 0 ) {
$problems [] = " [ $unit ] must eat food (upkeep > 0), or armies grow without limit. " ;
}
}
2026-10-29 09:28:20 +00:00
if ( max ( $config -> get ( 'combat.conquest.coin_cost' , [ 0 ])) > $maxCap ) {
$problems [] = 'A coin costs more than the largest storage holds.' ;
}
2026-10-28 20:39:48 +00:00
return $problems ;
}
2026-10-28 18:17:34 +00:00
private static function requirementsReachable ( WorldConfig $config , BuildingRules $rules ) : array
{
$problems = [];
foreach ( $config -> buildingTypes () as $type ) {
foreach ( $rules -> requires ( $type ) as $needed => $level ) {
if ( ! $config -> hasBuilding ( $needed )) {
$problems [] = " [ $type ] requires unknown type [ $needed ]. " ;
} elseif ( $level > $rules -> maxLevel ( $needed )) {
$problems [] = " [ $type ] requires [ $needed ] level $level , above its max level. " ;
}
}
}
$visiting = [];
$done = [];
$visit = function ( string $type ) use ( & $visit , & $visiting , & $done , & $problems , $config , $rules ) : void {
if ( isset ( $done [ $type ]) || ! $config -> hasBuilding ( $type )) {
return ;
}
if ( isset ( $visiting [ $type ])) {
$problems [] = " Requirement cycle through [ $type ]. " ;
return ;
}
$visiting [ $type ] = true ;
foreach ( array_keys ( $rules -> requires ( $type )) as $needed ) {
$visit ( $needed );
}
unset ( $visiting [ $type ]);
$done [ $type ] = true ;
};
foreach ( $config -> buildingTypes () as $type ) {
$visit ( $type );
}
return $problems ;
}
}