Merge remote-tracking branch 'remotes/upstream/main'

docs/adding games.md

@@ -60,7 +60,7 @@ These are "nice to have" features for a client, but they are not strictly requir
 if possible.
 
 * If your client appears in the Archipelago Launcher, you may define an icon for it that differentiates it from
-  other clients. The icon size is 38x38 pixels, but it will accept larger images with downscaling.
+  other clients. The icon size is 48x48 pixels, but smaller or larger images will scale to that size.
 
 ## World
 
@@ -109,6 +109,10 @@ subclass for webhost documentation and behaviors
 * A non-zero number of locations, added to your regions
 * A non-zero number of items **equal** to the number of locations, added to the multiworld itempool
   * In rare cases, there may be 0-location-0-item games, but this is extremely atypical.
+* A set 
+  [completion condition](https://github.com/ArchipelagoMW/Archipelago/blob/main/BaseClasses.py#L77) (aka "goal") for
+  the player.
+  * Use your player as the index (`multiworld.completion_condition[player]`) for your world's completion goal.
 
 ### Encouraged Features
 
@@ -142,11 +146,11 @@ workarounds or preferred methods which should be used instead:
   * If you need to place specific items, there are multiple ways to do so, but they should not be added to the 
     multiworld itempool.
 * It is not allowed to use `eval` for most reasons, chiefly due to security concerns. 
-* It is discouraged to use `yaml.load` directly due to security concerns.
-  * When possible, use `Utils.yaml_load` instead, as this defaults to the safe loader.
+* It is discouraged to use PyYAML (i.e. `yaml.load`) directly due to security concerns.
+  * When possible, use `Utils.parse_yaml` instead, as this defaults to the safe loader and the faster C parser.
 * When submitting regions or items to the multiworld (`multiworld.regions` and `multiworld.itempool` respectively), 
-  Do **not** use `=` as this will overwrite all elements for all games in the seed.
-  * Instead, use `append`, `extend`, or `+=`. 
+  do **not** use `=` as this will overwrite all elements for all games in the seed.
+  * Instead, use `append`, `extend`, or `+=`.
 
 ### Notable Caveats
 

docs/apworld_dev_faq.md

@@ -66,3 +66,22 @@ The reason entrance access rules using `location.can_reach` and `entrance.can_re
 We recognize it can feel like a trap since it will not alert you when you are missing an indirect condition, and that some games have very complex access rules.
 As of [PR #3682 (Core: Region handling customization)](https://github.com/ArchipelagoMW/Archipelago/pull/3682) being merged, it is possible for a world to opt out of indirect conditions entirely, instead using the system of checking each entrance whenever a region has been reached, although this does come with a performance cost.
 Opting out of using indirect conditions should only be used by games that *really* need it. For most games, it should be reasonable to know all entrance → region dependencies, making indirect conditions preferred because they are much faster.
+
+---
+
+### I uploaded the generated output of my world to the webhost and webhost is erroring on corrupted multidata
+
+The error `Could not load multidata. File may be corrupted or incompatible.` occurs when uploading a locally generated
+file where there is an issue with the multidata contained within it. It may come with a description like
+`(No module named 'worlds.myworld')` or `(global 'worlds.myworld.names.ItemNames' is forbidden)`
+
+Pickling is a way to compress python objects such that they can be decompressed and be used to rebuild the
+python objects. This means that if one of your custom class instances ends up in the multidata, the server would not
+be able to load that custom class to decompress the data, which can fail either because the custom class is unknown
+(because it cannot load your world module) or the class it's attempting to import to decompress is deemed unsafe.
+
+Common situations where this can happen include:
+* Using Option instances directly in slot_data. Ex: using `options.option_name` instead of `options.option_name.value`.
+  Also, consider using the `options.as_dict("option_name", "option_two")` helper.
+* Using enums as Location/Item names in the datapackage. When building out `location_name_to_id` and `item_name_to_id`,
+  make sure that you are not using your enum class for either the names or ids in these mappings.

docs/world api.md

@@ -606,8 +606,8 @@ from .items import get_item_type
 
 def set_rules(self) -> None:
     # For some worlds this step can be omitted if either a Logic mixin 
-    # (see below) is used, it's easier to apply the rules from data during
-    # location generation or everything is in generate_basic
+    # (see below) is used or it's easier to apply the rules from data during
+    # location generation
 
     # set a simple rule for an region
     set_rule(self.multiworld.get_entrance("Boss Door", self.player),