clarify commits

data/scenarios/Testing/1575-structure-recognizer/2201-initial-recognition-overlap.yaml

@@ -1,15 +1,22 @@
 version: 1
-name: Structure recognition - precluding overlaps
+name: Structure recognition - precluding initial overlaps
 description: |
   A cell may be a member of at most one structure.
+
+  Since recognition of pre-placed structures bypasses
+  the regular "search" process, we need to ensure that
+  overlaps are properly excluded by this alternate mechanism.
+  In this scenario, only the upper-left structure should be recognized,
+  based on the precedence criteria (structure size, then grid location)
 creative: false
 objectives:
   - teaser: Recognize exactly one structure
     goal:
       - |
         `square`{=structure} structure should be recognized upon scenario start.
       - |
-        Although two of these structures were initially placed, only one should be recognized.
+        Although two of these structures were initially placed, only
+        the upper-left one should be recognized.
     condition: |
       foundStructure <- structure "square" 0;
       return $ case foundStructure (\_. false) (\pair. fst pair == 1);

src/swarm-engine/Swarm/Game/State/Initialize.hs

@@ -177,6 +177,14 @@ pureScenarioToGameState scenario theSeed now toRun gsc =
 
   addRecipesWith f = IM.unionWith (<>) (f $ scenario ^. scenarioOperation . scenarioRecipes)
 
+-- |
+-- As part of initilizing the recognizer, we also pre-populate the
+-- list of "found" structures with those statically placed by the scenario definition.
+-- Note that this bypasses the regular "online" recognition machinery;
+-- we don't actually have to "search" for these structures since we are
+-- explicitly given their location; we only need to validate that each
+-- structure remains intact given other, potentially overlapping static placements.
+--
 mkRecognizer ::
   (Has (State GameState) sig m) =>
   StaticStructureInfo Cell ->
@@ -192,8 +200,6 @@ mkRecognizer structInfo@(StaticStructureInfo structDefs _) = do
       fs
       [IntactStaticPlacement $ map mkLogEntry foundIntact]
  where
-  -- NOTE: We assume that all static scenario placements are carefully arranged
-  -- so that overlapping structures are not simultaneously recognized.
   checkIntactness = sequenceA . (id &&& adaptGameState . ensureStructureIntact emptyFoundStructures mtlEntityAt)
 
   allPlaced = lookupStaticPlacements cellToEntity structInfo

src/swarm-topography/Swarm/Game/Scenario/Topography/Structure/Recognition/Registry.hs

@@ -86,10 +86,12 @@ addFound fs@(FoundStructure loc swg) (FoundRegistry byName byLoc) =
   k = getName $ originalDefinition swg
   occupationMap = M.fromList $ map (,fs) $ genOccupiedCoords fs
 
--- | Bulk insertion of found structures.
+-- | Bulk insertion of structures statically placed in the scenario definition.
 --
--- If any of these overlap, we can't be sure of the author's
--- intent as to which member of the overlap should take precedence,
+-- See the docs for 'Swarm.Game.State.Initialize.mkRecognizer' for more context.
+--
+-- Note that if any of these pre-placed structures overlap, we can't be sure of
+-- the author's intent as to which member of the overlap should take precedence,
 -- so perhaps it would be ideal to throw an error at scenario parse time.
 --
 -- However, determining whether a structure is all three of:
@@ -99,7 +101,7 @@ addFound fs@(FoundStructure loc swg) (FoundRegistry byName byLoc) =
 -- occurs at a later phase than scenario parse; it requires access to the 'GameState'.
 --
 -- So we just use the same sorting criteria as the one used to resolve recognition
--- conflicts at entity placement time.
+-- conflicts at entity placement time (see [STRUCTURE RECOGNIZER CONFLICT RESOLUTION]).
 populateStaticFoundStructures ::
   (Eq a, Eq b) =>
   [FoundStructure b a] ->

src/swarm-topography/Swarm/Game/Scenario/Topography/Structure/Recognition/Tracking.hs

@@ -259,10 +259,12 @@ registerRowMatches entLoader cLoc (AutomatonInfo horizontalOffsets pwMatcher) rS
   let candidatesChunked = findAll pwSM entitiesRow
   unrankedCandidateStructures <- checkCombo candidatesChunked
 
+  -- [STRUCTURE RECOGNIZER CONFLICT RESOLUTION]
   -- We only allow an entity to participate in one structure at a time,
   -- so multiple matches require a tie-breaker.
   -- The largest structure (by area) shall win.
-  -- Sort by decreasing order of preference.
+  -- Sort by decreasing order of preference
+  -- (see the Ord instance of 'FoundStructure').
   let rankedCandidates = sortOn Down unrankedCandidateStructures
   tell . pure . FoundCompleteStructureCandidates $
     map getStructInfo rankedCandidates

src/swarm-topography/Swarm/Game/Scenario/Topography/Structure/Recognition/Type.hs

@@ -301,7 +301,9 @@ data StructureIntactnessFailure e = StructureIntactnessFailure
   }
   deriving (Functor, Generic, ToJSON)
 
--- | Ordering is by increasing preference between simultaneously
+-- |
+-- [STRUCTURE RECOGNIZER CONFLICT RESOLUTION]
+-- Ordering is by increasing preference between simultaneously
 -- completed structures.
 -- The preference heuristic is for:
 --