diff --git a/worlds/messenger/__init__.py b/worlds/messenger/__init__.py index 8bde3bbc..2382a46c 100644 --- a/worlds/messenger/__init__.py +++ b/worlds/messenger/__init__.py @@ -46,8 +46,16 @@ class MessengerWeb(WebWorld): "setup/en", ["alwaysintreble"], ) + plando_en = Tutorial( + "The Messenger Plando Guide", + "A guide detailing The Messenger's various supported plando options.", + "English", + "plando_en.md", + "plando/en", + ["alwaysintreble"], + ) - tutorials = [tut_en] + tutorials = [tut_en, plando_en] class MessengerWorld(World): diff --git a/worlds/messenger/docs/plando_en.md b/worlds/messenger/docs/plando_en.md new file mode 100644 index 00000000..920cf029 --- /dev/null +++ b/worlds/messenger/docs/plando_en.md @@ -0,0 +1,101 @@ +# The Messenger Plando Guide + +This guide details the usage of the game-specific plando options that The Messenger has. The Messenger also supports the +generic item plando. For more information on what plando is and for information covering item plando, refer to the +[generic Archipelago plando guide](/tutorial/Archipelago/plando/en). The Messenger also uses the generic connection +plando system, but with specific behaviors that will be covered in this guide along with the other options. + +## Shop Price Plando + +This option allows you to specify prices for items in both shops. This also supports weighting, allowing you to choose +from multiple different prices for any given item. + +### Example + +```yaml +The Messenger: + shop_price_plan: + Karuta Plates: 50 + Devil's Due: 1 + Barmath'azel Figurine: + # left side is price, right side is weight + 500: 10 + 700: 5 + 1000: 20 +``` + +This block will make the item at the `Karuta Plates` node cost 50 shards, `Devil's Due` will cost 1 shard, and +`Barmath'azel Figurine` will cost either 500, 700, or 1000, with 1000 being the most likely with a 20/35 chance. + +## Portal Plando + +This option allows you to specify certain outputs for the portals. This option will only be checked if portal shuffle +and the `connections` plando host setting are enabled. + +A portal connection is plandoed by specifying an `entrance` and an `exit`. This option also supports `percentage`, which +is the percent chance that that connection occurs. The `entrance` is which portal is going to be entered, whereas the +`exit` is where the portal will lead and can include a shop location, a checkpoint, or any portal. However, the +portal exit must also be in the available pool for the selected portal shuffle option. For example, if portal shuffle is +set to `shops`, then the valid exits will only be portals and shops; any exit that is a checkpoint will not be valid. If +portal shuffle is set to `checkpoints`, you may not have multiple portals lead to the same area, e.g. `Seashell` and +`Spike Wave` may not both be used since they are both in Quillshroom Marsh. If the option is set to `anywhere`, then all +exits are valid. + +All valid connections for portal shuffle can be found by scrolling through the [portals module](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/messenger/portals.py#L12). +The entrance and exit should be written exactly as they appear within that file, except for when the **exit** point is a +portal. In that case, it should have "Portal" included. + +### Example + +```yaml +The Messenger: + portal_plando: + - entrance: Riviere Turquoise + exit: Wingsuit + - entrance: Sunken Shrine + exit: Sunny Day + - entrance: Searing Crags + exit: Glacial Peak Portal +``` + +This block will make it so that the Riviere Turquoise Portal will exit to the Wingsuit Shop, the Sunken Shrine Portal +will exit to the Sunny Day checkpoint, and the Searing Crags Portal will exit to the Glacial Peak Portal. + +## Transition Plando + +This option allows you to specify certain connections when using transition shuffle. This will only work if +transition shuffle and the `connections` plando host setting are enabled. + +Each transition connection is plandoed by specifying its attributes: + +* `entrance` is where you will enter this transition from. +* `exit` is where the transition will lead. +* `percentage` is the chance this connection will happen at all. +* `direction` is used to specify whether this connection will also go in reverse. This entry will be ignored if the + transition shuffle is set to `coupled` or if the specified connection can only occur in one direction, such as exiting + to Riviere Turquoise. The default direction is "both", which will make it so that returning through the exit + transition will return you to where you entered it from. "entrance" and "exit" are treated the same, with them both + making this transition only one-way. + +Valid connections can be found in the [`RANDOMIZED_CONNECTIONS` dictionary](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/messenger/connections.py#L640). +The keys (left) are entrances, and values (right) are exits. Whether you want the connection to go both ways or not, +both sides must either be two-way or one-way; E.g. connecting Artificer (Corrupted Future Portal) to one of the +Quillshroom Marsh entrances is not a valid pairing. A pairing can be determined to be two-way if both the entrance and +exit of that pair are an exit and entrance of another pairing, respectively. + +### Example + +```yaml +The Messenger: + plando_connections: + - entrance: Searing Crags - Top + exit: Dark Cave - Right + - entrance: Glacial Peak - Left + exit: Corrupted Future +``` + +This block will create the following connections: +1. Leaving Searing Crags towards Glacial Peak will take you to the beginning of Dark Cave, and leaving the Dark Cave + door will return you to the top of Searing Crags. +2. Taking Manfred to leave Glacial Peak, will take you to Corrupted Future. There is no reverse connection here so it + will always be one-way. diff --git a/worlds/messenger/options.py b/worlds/messenger/options.py index aaf152fb..6b041188 100644 --- a/worlds/messenger/options.py +++ b/worlds/messenger/options.py @@ -16,17 +16,8 @@ class MessengerAccessibility(ItemsAccessibility): class PortalPlando(PlandoConnections): """ - Plando connections to be used with portal shuffle. Direction is ignored. - List of valid connections can be found here: https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/messenger/portals.py#L12. - The entering Portal should *not* have "Portal" appended. - For the exits, those in checkpoints and shops should just be the name of the spot, while portals should have " Portal" at the end. - Example: - - entrance: Riviere Turquoise - exit: Wingsuit - - entrance: Sunken Shrine - exit: Sunny Day - - entrance: Searing Crags - exit: Glacial Peak Portal + Plando connections to be used with portal shuffle. + Documentation on using this can be found in The Messenger plando guide. """ display_name = "Portal Plando Connections" portals = [f"{portal} Portal" for portal in PORTALS] @@ -40,14 +31,7 @@ class PortalPlando(PlandoConnections): class TransitionPlando(PlandoConnections): """ Plando connections to be used with transition shuffle. - List of valid connections can be found at https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/messenger/connections.py#L641. - Dictionary keys (left) are entrances and values (right) are exits. If transition shuffle is on coupled all plando - connections will be coupled. If on decoupled, "entrance" and "exit" will be treated the same, simply making the - plando connection one-way from entrance to exit. - Example: - - entrance: Searing Crags - Top - exit: Dark Cave - Right - direction: both + Documentation on using this can be found in The Messenger plando guide. """ display_name = "Transition Plando Connections" entrances = frozenset(RANDOMIZED_CONNECTIONS.keys())