Merge branch 'proguseful' into apworld_variety_panelhunt_3

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,

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,
@@ -439,6 +454,7 @@ async def send_connect(self, **kwargs: typing.Any) -> None:
         if kwargs:
             payload.update(kwargs)
         await self.send_msgs([payload])
+        await self.send_msgs([{"cmd": "Get", "keys": ["_read_race_mode"]}])
 
     async def console_input(self) -> str:
         if self.ui:
@@ -459,13 +475,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 +515,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 +632,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 +646,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 +656,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"
@@ -987,6 +1008,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.')
@@ -1037,6 +1059,7 @@ async def main(args):
     parser.add_argument("url", nargs="?", help="Archipelago connection url")
     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)
         if url.scheme == "archipelago":
@@ -1048,6 +1071,7 @@ async def main(args):
         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))

Main.py

@@ -338,6 +338,7 @@ def precollect_hint(location):
                     "seed_name": multiworld.seed_name,
                     "spheres": spheres,
                     "datapackage": data_package,
+                    "race_mode": int(multiworld.is_race),
                 }
                 AutoWorld.call_all(multiworld, "modify_multidata", multidata)
 

MultiServer.py

@@ -15,6 +15,7 @@
 import operator
 import pickle
 import random
+import shlex
 import threading
 import time
 import typing
@@ -427,6 +428,8 @@ def _load(self, decoded_obj: dict, game_data_packages: typing.Dict[str, typing.A
               use_embedded_server_options: bool):
 
         self.read_data = {}
+        # there might be a better place to put this.
+        self.read_data["race_mode"] = lambda: decoded_obj.get("race_mode", 0)
         mdata_ver = decoded_obj["minimum_versions"]["server"]
         if mdata_ver > version_tuple:
             raise RuntimeError(f"Supplied Multidata (.archipelago) requires a server of at least version {mdata_ver},"
@@ -1150,7 +1153,7 @@ def __call__(self, raw: str) -> typing.Optional[bool]:
         if not raw:
             return
         try:
-            command = raw.split()
+            command = shlex.split(raw, comments=False)
             basecommand = command[0]
             if basecommand[0] == self.marker:
                 method = self.commands.get(basecommand[1:].lower(), None)

docs/network protocol.md

@@ -395,6 +395,7 @@ Some special keys exist with specific return data, all of them have the prefix `
 | item_name_groups_{game_name}     | dict\[str, list\[str\]\]      | item_name_groups belonging to the requested game.     |
 | location_name_groups_{game_name} | dict\[str, list\[str\]\]      | location_name_groups belonging to the requested game. |
 | client_status_{team}_{slot}      | [ClientStatus](#ClientStatus) | The current game status of the requested player.      |
+| race_mode                        | int                           | 0 if race mode is disabled, and 1 if it's enabled.    |
 
 ### Set
 Used to write data to the server's data storage, that data can then be shared across worlds or just saved for later. Values for keys in the data storage can be retrieved with a [Get](#Get) package, or monitored with a [SetNotify](#SetNotify) package.

kvui.py

@@ -243,6 +243,9 @@ def get_text(self):
                             f"\nYou currently have {ctx.hint_points} points."
                 elif ctx.hint_cost == 0:
                     text += "\n!hint is free to use."
+                if ctx.stored_data and "_read_race_mode" in ctx.stored_data:
+                    text += "\nRace mode is enabled." \
+                        if ctx.stored_data["_read_race_mode"] else "\nRace mode is disabled."
             else:
                 text += f"\nYou are not authenticated yet."
 

test/multiworld/test_multiworlds.py

@@ -71,7 +71,7 @@ def test_two_player_single_game_fills(self) -> None:
             for world in self.multiworld.worlds.values():
                 world.options.accessibility.value = Accessibility.option_full
             self.assertSteps(gen_steps)
-        with self.subTest("filling multiworld", seed=self.multiworld.seed):
-            distribute_items_restrictive(self.multiworld)
-            call_all(self.multiworld, "post_fill")
-            self.assertTrue(self.fulfills_accessibility(), "Collected all locations, but can't beat the game")
+            with self.subTest("filling multiworld", games=world_type.game, seed=self.multiworld.seed):
+                distribute_items_restrictive(self.multiworld)
+                call_all(self.multiworld, "post_fill")
+                self.assertTrue(self.fulfills_accessibility(), "Collected all locations, but can't beat the game")

worlds/AutoWorld.py

@@ -342,7 +342,7 @@ def __getattr__(self, item: str) -> Any:
 
     # overridable methods that get called by Main.py, sorted by execution order
     # can also be implemented as a classmethod and called "stage_<original_name>",
-    # in that case the MultiWorld object is passed as an argument, and it gets called once for the entire multiworld.
+    # in that case the MultiWorld object is passed as the first argument, and it gets called once for the entire multiworld.
     # An example of this can be found in alttp as stage_pre_fill
 
     @classmethod

worlds/_bizhawk/__init__.py

@@ -223,8 +223,8 @@ async def set_message_interval(ctx: BizHawkContext, value: float) -> None:
         raise SyncError(f"Expected response of type SET_MESSAGE_INTERVAL_RESPONSE but got {res['type']}")
 
 
-async def guarded_read(ctx: BizHawkContext, read_list: typing.List[typing.Tuple[int, int, str]],
-                       guard_list: typing.List[typing.Tuple[int, typing.Iterable[int], str]]) -> typing.Optional[typing.List[bytes]]:
+async def guarded_read(ctx: BizHawkContext, read_list: typing.Sequence[typing.Tuple[int, int, str]],
+                       guard_list: typing.Sequence[typing.Tuple[int, typing.Sequence[int], str]]) -> typing.Optional[typing.List[bytes]]:
     """Reads an array of bytes at 1 or more addresses if and only if every byte in guard_list matches its expected
     value.
 
@@ -266,7 +266,7 @@ async def guarded_read(ctx: BizHawkContext, read_list: typing.List[typing.Tuple[
     return ret
 
 
-async def read(ctx: BizHawkContext, read_list: typing.List[typing.Tuple[int, int, str]]) -> typing.List[bytes]:
+async def read(ctx: BizHawkContext, read_list: typing.Sequence[typing.Tuple[int, int, str]]) -> typing.List[bytes]:
     """Reads data at 1 or more addresses.
 
     Items in `read_list` should be organized `(address, size, domain)` where
@@ -278,8 +278,8 @@ async def read(ctx: BizHawkContext, read_list: typing.List[typing.Tuple[int, int
     return await guarded_read(ctx, read_list, [])
 
 
-async def guarded_write(ctx: BizHawkContext, write_list: typing.List[typing.Tuple[int, typing.Iterable[int], str]],
-                        guard_list: typing.List[typing.Tuple[int, typing.Iterable[int], str]]) -> bool:
+async def guarded_write(ctx: BizHawkContext, write_list: typing.Sequence[typing.Tuple[int, typing.Sequence[int], str]],
+                        guard_list: typing.Sequence[typing.Tuple[int, typing.Sequence[int], str]]) -> bool:
     """Writes data to 1 or more addresses if and only if every byte in guard_list matches its expected value.
 
     Items in `write_list` should be organized `(address, value, domain)` where
@@ -316,7 +316,7 @@ async def guarded_write(ctx: BizHawkContext, write_list: typing.List[typing.Tupl
     return True
 
 
-async def write(ctx: BizHawkContext, write_list: typing.List[typing.Tuple[int, typing.Iterable[int], str]]) -> None:
+async def write(ctx: BizHawkContext, write_list: typing.Sequence[typing.Tuple[int, typing.Sequence[int], str]]) -> None:
     """Writes data to 1 or more addresses.
 
     Items in write_list should be organized `(address, value, domain)` where

worlds/bumpstik/__init__.py

@@ -125,6 +125,6 @@ def set_rules(self):
             lambda state: state.has("Hazard Bumper", self.player, 25)
 
         self.multiworld.completion_condition[self.player] = \
-            lambda state: state.has("Booster Bumper", self.player, 5) and \
-            state.has("Treasure Bumper", self.player, 32)
+            lambda state: state.has_all_counts({"Booster Bumper": 5, "Treasure Bumper": 32, "Hazard Bumper": 25}, \
+                self.player)
 

worlds/dark_souls_3/docs/setup_en.md

@@ -3,16 +3,17 @@
 ## Required Software
 
 - [Dark Souls III](https://store.steampowered.com/app/374320/DARK_SOULS_III/)
-- [Dark Souls III AP Client](https://github.com/Marechal-L/Dark-Souls-III-Archipelago-client/releases)
+- [Dark Souls III AP Client](https://github.com/nex3/Dark-Souls-III-Archipelago-client/releases/latest)
 
 ## Optional Software
 
 - Map tracker not yet updated for 3.0.0
 
 ## Setting Up
 
-First, download the client from the link above. It doesn't need to go into any particular directory;
-it'll automatically locate _Dark Souls III_ in your Steam installation folder.
+First, download the client from the link above (`DS3.Archipelago.*.zip`). It doesn't need to go
+into any particular directory; it'll automatically locate _Dark Souls III_ in your Steam
+installation folder.
 
 Version 3.0.0 of the randomizer _only_ supports the latest version of _Dark Souls III_, 1.15.2. This
 is the latest version, so you don't need to do any downpatching! However, if you've already
@@ -35,8 +36,9 @@ randomized item and (optionally) enemy locations. You only need to do this once
 
 To run _Dark Souls III_ in Archipelago mode:
 
-1. Start Steam. **Do not run in offline mode.** The mod will make sure you don't connect to the
-   DS3 servers, and running Steam in offline mode will make certain scripted invaders fail to spawn.
+1. Start Steam. **Do not run in offline mode.** Running Steam in offline mode will make certain
+   scripted invaders fail to spawn. Instead, change the game itself to offline mode on the menu
+   screen.
 
 2. Run `launchmod_darksouls3.bat`. This will start _Dark Souls III_ as well as a command prompt that
    you can use to interact with the Archipelago server.
@@ -52,4 +54,21 @@ To run _Dark Souls III_ in Archipelago mode:
 ### Where do I get a config file?
 
 The [Player Options](/games/Dark%20Souls%20III/player-options) page on the website allows you to
-configure your personal options and export them into a config file.
+configure your personal options and export them into a config file. The [AP client archive] also
+includes an options template.
+
+[AP client archive]: https://github.com/nex3/Dark-Souls-III-Archipelago-client/releases/latest
+
+### Does this work with Proton?
+
+The *Dark Souls III* Archipelago randomizer supports running on Linux under Proton. There are a few
+things to keep in mind:
+
+* Because `DS3Randomizer.exe` relies on the .NET runtime, you'll need to install
+  the [.NET Runtime] under **plain [WINE]**, then run `DS3Randomizer.exe` under
+  plain WINE as well. It won't work as a Proton app!
+
+* To run the game itself, just run `launchmod_darksouls3.bat` under Proton.
+
+[.NET Runtime]: https://dotnet.microsoft.com/en-us/download/dotnet/8.0
+[WINE]: https://www.winehq.org/