Merge branch 'ArchipelagoMW:main' into main

docs/entrance randomization.md

@@ -370,19 +370,13 @@ target_group_lookup = bake_target_group_lookup(world, get_target_groups)
 
 #### When to call `randomize_entrances`
 
-The short answer is that you will almost always want to do ER in `pre_fill`. For more information why, continue reading.
+The correct step for this is `World.connect_entrances`.
 
-ER begins by collecting the entire item pool and then uses your access rules to try and prevent some kinds of failures. 
-This means 2 things about when you can call ER:
-1. You must supply your item pool before calling ER, or call ER before setting any rules which require items.
-2. If you have rules dependent on anything other than items (e.g. `Entrance`s or events), you must set your rules
-   and create your events before you call ER if you want to guarantee a correct output.
-
-If the conditions above are met, you could theoretically do ER as early as `create_regions`. However, plando is also 
-a consideration. Since item plando happens between `set_rules` and `pre_fill` and modifies the item pool, doing ER 
-in `pre_fill` is the only way to account for placements made by item plando, otherwise you risk impossible seeds or 
-generation failures. Obviously, if your world implements entrance plando, you will likely want to do that before ER as
-well.
+Currently, you could theoretically do it as early as `World.create_regions` or as late as `pre_fill`.
+However, there are upcoming changes to Item Plando and Generic Entrance Randomizer to make the two features work better
+together.
+These changes necessitate that entrance randomization is done exactly in `World.connect_entrances`.
+It is fine for your Entrances to be connected differently or not at all before this step.
 
 #### Informing your client about randomized entrances
 

docs/network protocol.md

@@ -261,6 +261,7 @@ Sent to clients in response to a [Set](#Set) package if want_reply was set to tr
 | key            | str  | The key that was updated.                                                                  |
 | value          | any  | The new value for the key.                                                                 |
 | original_value | any  | The value the key had before it was updated. Not present on "_read" prefixed special keys. |
+| slot           | int  | The slot that originally sent the Set package causing this change.                         |
 
 Additional arguments added to the [Set](#Set) package that triggered this [SetReply](#SetReply) will also be passed along.
 

docs/world api.md

@@ -222,8 +222,8 @@ could also be progress in a research tree, or even something more abstract like
 
 Each location has a `name` and an `address` (hereafter referred to as an `id`), is placed in a Region, has access rules,
 and has a classification. The name needs to be unique within each game and must not be numeric (must contain least 1
-letter or symbol). The ID needs to be unique across all games, and is best kept in the same range as the item IDs.
-Locations and items can share IDs, so typically a game's locations and items start at the same ID.
+letter or symbol). The ID needs to be unique across all locations within the game. 
+Locations and items can share IDs, and locations can share IDs with other games' locations.
 
 World-specific IDs must be in the range 1 to 2<sup>53</sup>-1; IDs ≤ 0 are global and reserved.
 
@@ -243,7 +243,9 @@ progression. Progression items will be assigned to locations with higher priorit
 and satisfy progression balancing.
 
 The name needs to be unique within each game, meaning if you need to create multiple items with the same name, they
-will all have the same ID. Name must not be numeric (must contain at least 1 letter or symbol).
+will all have the same ID. Name must not be numeric (must contain at least 1 letter or symbol). 
+The ID thus also needs to be unique across all items with different names within the game. 
+Items and locations can share IDs, and items can share IDs with other games' items.
 
 Other classifications include:
 
@@ -490,6 +492,9 @@ In addition, the following methods can be implemented and are called in this ord
   after this step. Locations cannot be moved to different regions after this step.
 * `set_rules(self)`
   called to set access and item rules on locations and entrances.
+* `connect_entrances(self)`
+  by the end of this step, all entrances must exist and be connected to their source and target regions.
+  Entrance randomization should be done here.
 * `generate_basic(self)`
   player-specific randomization that does not affect logic can be done here.
 * `pre_fill(self)`, `fill_hook(self)` and `post_fill(self)`
@@ -835,14 +840,16 @@ def generate_output(self, output_directory: str) -> None:
 
 ### Slot Data
 
-If the game client needs to know information about the generated seed, a preferred method of transferring the data
-is through the slot data. This is filled with the `fill_slot_data` method of your world by returning
-a `dict` with `str` keys that can be serialized with json.
-But, to not waste resources, it should be limited to data that is absolutely necessary. Slot data is sent to your client
-once it has successfully [connected](network%20protocol.md#connected).
+If a client or tracker needs to know information about the generated seed, a preferred method of transferring the data 
+is through the slot data. This is filled with the `fill_slot_data` method of your world by returning a `dict` with 
+`str` keys that can be serialized with json. However, to not waste resources, it should be limited to data that is 
+absolutely necessary. Slot data is sent to your client once it has successfully 
+[connected](network%20protocol.md#connected).
+
 If you need to know information about locations in your world, instead of propagating the slot data, it is preferable
-to use [LocationScouts](network%20protocol.md#locationscouts), since that data already exists on the server. The most
-common usage of slot data is sending option results that the client needs to be aware of.
+to use [LocationScouts](network%20protocol.md#locationscouts), since that data already exists on the server. Adding 
+item/location pairs is unnecessary since the AP server already retains and freely gives that information to clients 
+that request it. The most common usage of slot data is sending option results that the client needs to be aware of.
 
 ```python
 def fill_slot_data(self) -> Dict[str, Any]: