Docs on ERPlacementState, add coupled/uncoupled handling to deadend d…

…etection

entrance_rando.py

@@ -52,12 +52,14 @@ def remove(self, entrance: Entrance) -> None:
     others: GroupLookup
     _random: random.Random
     _leads_to_exits_cache: Dict[Entrance, bool]
+    _coupled: bool
 
-    def __init__(self, rng: random.Random):
+    def __init__(self, rng: random.Random, coupled: bool):
         self.dead_ends = EntranceLookup.GroupLookup()
         self.others = EntranceLookup.GroupLookup()
         self._random = rng
         self._leads_to_exits_cache = {}
+        self._coupled = coupled
 
     def _can_lead_to_randomizable_exits(self, entrance: Entrance) -> bool:
         """
@@ -79,8 +81,10 @@ def _can_lead_to_randomizable_exits(self, entrance: Entrance) -> bool:
             visited.add(region)
 
             for exit_ in region.exits:
-                # randomizable and not the reverse of the start entrance
-                if not exit_.connected_region and exit_.name != entrance.name:
+                # randomizable exits which are not reverse of the incoming entrance.
+                # uncoupled mode is an exception because in this case going back in the door you just came in could
+                # actually lead somewhere new
+                if not exit_.connected_region and (not self._coupled or exit_.name != entrance.name):
                     self._leads_to_exits_cache[entrance] = True
                     return True
                 elif exit_.connected_region and exit_.connected_region not in visited:
@@ -119,18 +123,24 @@ def __len__(self):
 
 
 class ERPlacementState:
+    """The state of an ongoing or completed entrance randomization"""
     placements: List[Entrance]
+    """The list of randomized Entrance objects which have been connected successfully"""
     pairings: List[Tuple[str, str]]
+    """A list of pairings of connected entrance names, of the form (source_exit, target_entrance)"""
     world: World
+    """The world which is having its entrances randomized"""
     collection_state: CollectionState
+    """The CollectionState backing the entrance randomization logic"""
     coupled: bool
+    """Whether entrance randomization is operating in coupled mode"""
 
     def __init__(self, world: World, coupled: bool):
         self.placements = []
         self.pairings = []
         self.world = world
-        self.collection_state = world.multiworld.get_all_state(False, True)
         self.coupled = coupled
+        self.collection_state = world.multiworld.get_all_state(False, True)
 
     @property
     def placed_regions(self) -> Set[Region]:
@@ -250,7 +260,7 @@ def randomize_entrances(
     """
     start_time = time.perf_counter()
     er_state = ERPlacementState(world, coupled)
-    entrance_lookup = EntranceLookup(world.random)
+    entrance_lookup = EntranceLookup(world.random, coupled)
     # similar to fill, skip validity checks on entrances if the game is beatable on minimal accessibility
     perform_validity_check = True
 

test/general/test_entrance_rando.py

@@ -64,7 +64,7 @@ def test_shuffled_targets(self):
         multiworld = generate_test_multiworld()
         generate_disconnected_region_grid(multiworld, 5)
 
-        lookup = EntranceLookup(multiworld.per_slot_randoms[1])
+        lookup = EntranceLookup(multiworld.per_slot_randoms[1], coupled=True)
         er_targets = [entrance for region in multiworld.get_regions(1)
                       for entrance in region.entrances if not entrance.parent_region]
         for entrance in er_targets:
@@ -83,7 +83,7 @@ def test_ordered_targets(self):
         multiworld = generate_test_multiworld()
         generate_disconnected_region_grid(multiworld, 5)
 
-        lookup = EntranceLookup(multiworld.per_slot_randoms[1])
+        lookup = EntranceLookup(multiworld.per_slot_randoms[1], coupled=True)
         er_targets = [entrance for region in multiworld.get_regions(1)
                       for entrance in region.entrances if not entrance.parent_region]
         for entrance in er_targets: