Merge branch 'main' into not_none

.github/workflows/unittests.yml

@@ -37,12 +37,13 @@ jobs:
           - {version: '3.9'}
           - {version: '3.10'}
           - {version: '3.11'}
+          - {version: '3.12'}
         include:
           - python: {version: '3.8'}  # win7 compat
             os: windows-latest
-          - python: {version: '3.11'}  # current
+          - python: {version: '3.12'}  # current
             os: windows-latest
-          - python: {version: '3.11'}  # current
+          - python: {version: '3.12'}  # current
             os: macos-latest
 
     steps:
@@ -70,7 +71,7 @@ jobs:
         os:
           - ubuntu-latest
         python:
-          - {version: '3.11'}  # current
+          - {version: '3.12'}  # current
 
     steps:
     - uses: actions/checkout@v4

BaseClasses.py

@@ -194,7 +194,9 @@ def add_group(self, name: str, game: str, players: AbstractSet[int] = frozenset(
         self.player_types[new_id] = NetUtils.SlotType.group
         world_type = AutoWorld.AutoWorldRegister.world_types[game]
         self.worlds[new_id] = world_type.create_group(self, new_id, players)
-        self.worlds[new_id].collect_item = classmethod(AutoWorld.World.collect_item).__get__(self.worlds[new_id])
+        self.worlds[new_id].collect_item = AutoWorld.World.collect_item.__get__(self.worlds[new_id])
+        self.worlds[new_id].collect = AutoWorld.World.collect.__get__(self.worlds[new_id])
+        self.worlds[new_id].remove = AutoWorld.World.remove.__get__(self.worlds[new_id])
         self.player_name[new_id] = name
 
         new_group = self.groups[new_id] = Group(name=name, game=game, players=players,
@@ -342,6 +344,8 @@ def find_common_pool(players: Set[int], shared_pool: Set[str]) -> Tuple[
             region = Region("Menu", group_id, self, "ItemLink")
             self.regions.append(region)
             locations = region.locations
+            # ensure that progression items are linked first, then non-progression
+            self.itempool.sort(key=lambda item: item.advancement)
             for item in self.itempool:
                 count = common_item_count.get(item.player, {}).get(item.name, 0)
                 if count:
@@ -692,25 +696,33 @@ def __init__(self, parent: MultiWorld):
 
     def update_reachable_regions(self, player: int):
         self.stale[player] = False
+        world: AutoWorld.World = self.multiworld.worlds[player]
         reachable_regions = self.reachable_regions[player]
-        blocked_connections = self.blocked_connections[player]
         queue = deque(self.blocked_connections[player])
-        start = self.multiworld.get_region("Menu", player)
+        start: Region = world.get_region(world.origin_region_name)
 
         # init on first call - this can't be done on construction since the regions don't exist yet
         if start not in reachable_regions:
             reachable_regions.add(start)
-            blocked_connections.update(start.exits)
+            self.blocked_connections[player].update(start.exits)
             queue.extend(start.exits)
 
+        if world.explicit_indirect_conditions:
+            self._update_reachable_regions_explicit_indirect_conditions(player, queue)
+        else:
+            self._update_reachable_regions_auto_indirect_conditions(player, queue)
+
+    def _update_reachable_regions_explicit_indirect_conditions(self, player: int, queue: deque):
+        reachable_regions = self.reachable_regions[player]
+        blocked_connections = self.blocked_connections[player]
         # run BFS on all connections, and keep track of those blocked by missing items
         while queue:
             connection = queue.popleft()
             new_region = connection.connected_region
             if new_region in reachable_regions:
                 blocked_connections.remove(connection)
             elif connection.can_reach(self):
-                assert new_region, f"tried to search through an Entrance \"{connection}\" with no Region"
+                assert new_region, f"tried to search through an Entrance \"{connection}\" with no connected Region"
                 reachable_regions.add(new_region)
                 blocked_connections.remove(connection)
                 blocked_connections.update(new_region.exits)
@@ -722,6 +734,29 @@ def update_reachable_regions(self, player: int):
                     if new_entrance in blocked_connections and new_entrance not in queue:
                         queue.append(new_entrance)
 
+    def _update_reachable_regions_auto_indirect_conditions(self, player: int, queue: deque):
+        reachable_regions = self.reachable_regions[player]
+        blocked_connections = self.blocked_connections[player]
+        new_connection: bool = True
+        # run BFS on all connections, and keep track of those blocked by missing items
+        while new_connection:
+            new_connection = False
+            while queue:
+                connection = queue.popleft()
+                new_region = connection.connected_region
+                if new_region in reachable_regions:
+                    blocked_connections.remove(connection)
+                elif connection.can_reach(self):
+                    assert new_region, f"tried to search through an Entrance \"{connection}\" with no Region"
+                    reachable_regions.add(new_region)
+                    blocked_connections.remove(connection)
+                    blocked_connections.update(new_region.exits)
+                    queue.extend(new_region.exits)
+                    self.path[new_region] = (new_region.name, self.path.get(connection, None))
+                    new_connection = True
+            # sweep for indirect connections, mostly Entrance.can_reach(unrelated_Region)
+            queue.extend(blocked_connections)
+
     def copy(self) -> CollectionState:
         ret = CollectionState(self.multiworld)
         ret.prog_items = {player: counter.copy() for player, counter in self.prog_items.items()}
@@ -913,6 +948,7 @@ def __init__(self, player: int, name: str = "", parent: Optional[Region] = None)
         self.player = player
 
     def can_reach(self, state: CollectionState) -> bool:
+        assert self.parent_region, f"called can_reach on an Entrance \"{self}\" with no parent_region"
         if self.parent_region.can_reach(state) and self.access_rule(state):
             if not self.hide_path and not self in state.path:
                 state.path[self] = (self.name, state.path.get(self.parent_region, (self.parent_region.name, None)))
@@ -1133,7 +1169,7 @@ def can_fill(self, state: CollectionState, item: Item, check_access: bool = True
 
     def can_reach(self, state: CollectionState) -> bool:
         # Region.can_reach is just a cache lookup, so placing it first for faster abort on average
-        assert self.parent_region, "Can't reach location without region"
+        assert self.parent_region, f"called can_reach on a Location \"{self}\" with no parent_region"
         return self.parent_region.can_reach(state) and self.access_rule(state)
 
     def place_locked_item(self, item: Item):
@@ -1176,7 +1212,7 @@ class ItemClassification(IntFlag):
     filler = 0b0000  # aka trash, as in filler items like ammo, currency etc,
     progression = 0b0001  # Item that is logically relevant
     useful = 0b0010  # Item that is generally quite useful, but not required for anything logical
-    trap = 0b0100  # detrimental or entirely useless (nothing) item
+    trap = 0b0100  # detrimental item
     skip_balancing = 0b1000  # should technically never occur on its own
     # Item that is logically relevant, but progression balancing should not touch.
     # Typically currency or other counted items.

BizHawkClient.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
+import sys
 import ModuleUpdate
 ModuleUpdate.update()
 
 from worlds._bizhawk.context import launch
 
 if __name__ == "__main__":
-    launch()
+    launch(*sys.argv[1:])

CommonClient.py

@@ -45,10 +45,21 @@ def get_ssl_context():
 
 
 class ClientCommandProcessor(CommandProcessor):
+    """
+    The Command Processor will parse every method of the class that starts with "_cmd_" as a command to be called
+    when parsing user input, i.e. _cmd_exit will be called when the user sends the command "/exit".
+
+    The decorator @mark_raw can be imported from MultiServer and tells the parser to only split on the first
+    space after the command i.e. "/exit one two three" will be passed in as method("one two three") with mark_raw
+    and method("one", "two", "three") without.
+
+    In addition all docstrings for command methods will be displayed to the user on launch and when using "/help"
+    """
     def __init__(self, ctx: CommonContext):
         self.ctx = ctx
 
     def output(self, text: str):
+        """Helper function to abstract logging to the CommonClient UI"""
         logger.info(text)
 
     def _cmd_exit(self) -> bool:
@@ -164,13 +175,14 @@ def _cmd_ready(self):
         async_start(self.ctx.send_msgs([{"cmd": "StatusUpdate", "status": state}]), name="send StatusUpdate")
 
     def default(self, raw: str):
+        """The default message parser to be used when parsing any messages that do not match a command"""
         raw = self.ctx.on_user_say(raw)
         if raw:
             async_start(self.ctx.send_msgs([{"cmd": "Say", "text": raw}]), name="send Say")
 
 
 class CommonContext:
-    # Should be adjusted as needed in subclasses
+    # The following attributes are used to Connect and should be adjusted as needed in subclasses
     tags: typing.Set[str] = {"AP"}
     game: typing.Optional[str] = None
     items_handling: typing.Optional[int] = None
@@ -429,7 +441,10 @@ async def get_username(self):
                 self.auth = await self.console_input()
 
     async def send_connect(self, **kwargs: typing.Any) -> None:
-        """ send `Connect` packet to log in to server """
+        """
+        Send a `Connect` packet to log in to the server,
+        additional keyword args can override any value in the connection packet
+        """
         payload = {
             'cmd': 'Connect',
             'password': self.password, 'name': self.auth, 'version': Utils.version_tuple,
@@ -459,13 +474,15 @@ def cancel_autoreconnect(self) -> bool:
         return False
 
     def slot_concerns_self(self, slot) -> bool:
+        """Helper function to abstract player groups, should be used instead of checking slot == self.slot directly."""
         if slot == self.slot:
             return True
         if slot in self.slot_info:
             return self.slot in self.slot_info[slot].group_members
         return False
 
     def is_echoed_chat(self, print_json_packet: dict) -> bool:
+        """Helper function for filtering out messages sent by self."""
         return print_json_packet.get("type", "") == "Chat" \
             and print_json_packet.get("team", None) == self.team \
             and print_json_packet.get("slot", None) == self.slot
@@ -497,13 +514,14 @@ def on_user_say(self, text: str) -> typing.Optional[str]:
         """Gets called before sending a Say to the server from the user.
         Returned text is sent, or sending is aborted if None is returned."""
         return text
-    
+
     def on_ui_command(self, text: str) -> None:
         """Gets called by kivy when the user executes a command starting with `/` or `!`.
         The command processor is still called; this is just intended for command echoing."""
         self.ui.print_json([{"text": text, "type": "color", "color": "orange"}])
 
     def update_permissions(self, permissions: typing.Dict[str, int]):
+        """Internal method to parse and save server permissions from RoomInfo"""
         for permission_name, permission_flag in permissions.items():
             try:
                 flag = Permission(permission_flag)
@@ -613,6 +631,7 @@ def on_deathlink(self, data: typing.Dict[str, typing.Any]) -> None:
             logger.info(f"DeathLink: Received from {data['source']}")
 
     async def send_death(self, death_text: str = ""):
+        """Helper function to send a deathlink using death_text as the unique death cause string."""
         if self.server and self.server.socket:
             logger.info("DeathLink: Sending death to your friends...")
             self.last_death_link = time.time()
@@ -626,6 +645,7 @@ async def send_death(self, death_text: str = ""):
             }])
 
     async def update_death_link(self, death_link: bool):
+        """Helper function to set Death Link connection tag on/off and update the connection if already connected."""
         old_tags = self.tags.copy()
         if death_link:
             self.tags.add("DeathLink")
@@ -635,7 +655,7 @@ async def update_death_link(self, death_link: bool):
             await self.send_msgs([{"cmd": "ConnectUpdate", "tags": self.tags}])
 
     def gui_error(self, title: str, text: typing.Union[Exception, str]) -> typing.Optional["kvui.MessageBox"]:
-        """Displays an error messagebox"""
+        """Displays an error messagebox in the loaded Kivy UI. Override if using a different UI framework"""
         if not self.ui:
             return None
         title = title or "Error"
@@ -662,17 +682,19 @@ def handle_connection_loss(self, msg: str) -> None:
         logger.exception(msg, exc_info=exc_info, extra={'compact_gui': True})
         self._messagebox_connection_loss = self.gui_error(msg, exc_info[1])
 
-    def run_gui(self):
-        """Import kivy UI system and start running it as self.ui_task."""
+    def make_gui(self) -> typing.Type["kvui.GameManager"]:
+        """To return the Kivy App class needed for run_gui so it can be overridden before being built"""
         from kvui import GameManager
 
         class TextManager(GameManager):
-            logging_pairs = [
-                ("Client", "Archipelago")
-            ]
             base_title = "Archipelago Text Client"
 
-        self.ui = TextManager(self)
+        return TextManager
+
+    def run_gui(self):
+        """Import kivy UI system from make_gui() and start running it as self.ui_task."""
+        ui_class = self.make_gui()
+        self.ui = ui_class(self)
         self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
 
     def run_cli(self):
@@ -985,6 +1007,7 @@ async def console_loop(ctx: CommonContext):
 
 
 def get_base_parser(description: typing.Optional[str] = None):
+    """Base argument parser to be reused for components subclassing off of CommonClient"""
     import argparse
     parser = argparse.ArgumentParser(description=description)
     parser.add_argument('--connect', default=None, help='Address of the multiworld host.')
@@ -994,7 +1017,7 @@ def get_base_parser(description: typing.Optional[str] = None):
     return parser
 
 
-def run_as_textclient():
+def run_as_textclient(*args):
     class TextContext(CommonContext):
         # Text Mode to use !hint and such with games that have no text entry
         tags = CommonContext.tags | {"TextOnly"}
@@ -1033,16 +1056,21 @@ async def main(args):
     parser = get_base_parser(description="Gameless Archipelago Client, for text interfacing.")
     parser.add_argument('--name', default=None, help="Slot Name to connect as.")
     parser.add_argument("url", nargs="?", help="Archipelago connection url")
-    args = parser.parse_args()
+    args = parser.parse_args(args)
 
+    # handle if text client is launched using the "archipelago://name:pass@host:port" url from webhost
     if args.url:
         url = urllib.parse.urlparse(args.url)
-        args.connect = url.netloc
-        if url.username:
-            args.name = urllib.parse.unquote(url.username)
-        if url.password:
-            args.password = urllib.parse.unquote(url.password)
+        if url.scheme == "archipelago":
+            args.connect = url.netloc
+            if url.username:
+                args.name = urllib.parse.unquote(url.username)
+            if url.password:
+                args.password = urllib.parse.unquote(url.password)
+        else:
+            parser.error(f"bad url, found {args.url}, expected url in form of archipelago://archipelago.gg:38281")
 
+    # use colorama to display colored text highlighting on windows
     colorama.init()
 
     asyncio.run(main(args))
@@ -1051,4 +1079,4 @@ async def main(args):
 
 if __name__ == '__main__':
     logging.getLogger().setLevel(logging.INFO)  # force log-level to work around log level resetting to WARNING
-    run_as_textclient()
+    run_as_textclient(*sys.argv[1:])  # default value for parse_args

Fill.py

@@ -475,28 +475,26 @@ def mark_for_locking(location: Location):
         nonlocal lock_later
         lock_later.append(location)
 
+    single_player = multiworld.players == 1 and not multiworld.groups
+
     if prioritylocations:
         # "priority fill"
         fill_restrictive(multiworld, multiworld.state, prioritylocations, progitempool,
-                         single_player_placement=multiworld.players == 1, swap=False, on_place=mark_for_locking,
-                         name="Priority")
+                         single_player_placement=single_player, swap=False, on_place=mark_for_locking, name="Priority")
         accessibility_corrections(multiworld, multiworld.state, prioritylocations, progitempool)
         defaultlocations = prioritylocations + defaultlocations
 
     if progitempool:
         # "advancement/progression fill"
         if panic_method == "swap":
-            fill_restrictive(multiworld, multiworld.state, defaultlocations, progitempool,
-                             swap=True,
-                             name="Progression", single_player_placement=multiworld.players == 1)
+            fill_restrictive(multiworld, multiworld.state, defaultlocations, progitempool, swap=True,
+                             name="Progression", single_player_placement=single_player)
         elif panic_method == "raise":
-            fill_restrictive(multiworld, multiworld.state, defaultlocations, progitempool,
-                             swap=False,
-                             name="Progression", single_player_placement=multiworld.players == 1)
+            fill_restrictive(multiworld, multiworld.state, defaultlocations, progitempool, swap=False,
+                             name="Progression", single_player_placement=single_player)
         elif panic_method == "start_inventory":
-            fill_restrictive(multiworld, multiworld.state, defaultlocations, progitempool,
-                             swap=False, allow_partial=True,
-                             name="Progression", single_player_placement=multiworld.players == 1)
+            fill_restrictive(multiworld, multiworld.state, defaultlocations, progitempool, swap=False,
+                             allow_partial=True, name="Progression", single_player_placement=single_player)
             if progitempool:
                 for item in progitempool:
                     logging.debug(f"Moved {item} to start_inventory to prevent fill failure.")