From 099c4fca3c4d6da34bbfee43be4fbce64740c3f4 Mon Sep 17 00:00:00 2001 From: recklesscoder <57289227+recklesscoder@users.noreply.github.com> Date: Mon, 10 Oct 2022 09:10:01 +0200 Subject: [PATCH] Docs: Polished Trigger and Plando guides (#1080) * Docs: Polished Trigger and Plando guides * Docs: Trigger/Plando guide polish PR suggestions by SoldierofOrder Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> * Docs: More Trigger/Plando guide polish Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> --- worlds/generic/docs/plando_en.md | 83 ++++++++++++------------- worlds/generic/docs/triggers_en.md | 97 ++++++++++++++---------------- 2 files changed, 88 insertions(+), 92 deletions(-) diff --git a/worlds/generic/docs/plando_en.md b/worlds/generic/docs/plando_en.md index fa3edd1f..c9f70fcb 100644 --- a/worlds/generic/docs/plando_en.md +++ b/worlds/generic/docs/plando_en.md @@ -2,23 +2,24 @@ ## What is Plando? -The purposes of randomizers is to randomize the items in a game to give a new experience. Plando takes this concept and +The purpose of randomizers is to randomize the items in a game to give a new experience. Plando takes this concept and changes it up by allowing you to plan out certain aspects of the game by placing certain items in certain locations, certain bosses in certain rooms, edit text for certain NPCs/signs, or even force certain region connections. Each of these options are going to be detailed separately as `item plando`, `boss plando`, `text plando`, -and `connection plando`. Every game in archipelago supports item plando but the other plando options are only supported -by certain games. Currently, only LTTP supports text and boss plando. Support for connection plando may vary. +and `connection plando`. Every game in Archipelago supports item plando but the other plando options are only supported +by certain games. Currently, only A Link to the Past supports text and boss plando. Support for connection plando may +vary. ### Enabling Plando -On the website plando will already be enabled. If you will be generating the game locally plando features must be +On the website, plando will already be enabled. If you will be generating the game locally, plando features must be enabled (opt-in). -* To opt-in go to the archipelago installation (default: `C:\ProgramData\Archipelago`), open the host.yaml with a text +* To opt-in go to the Archipelago installation (default: `C:\ProgramData\Archipelago`), open `host.yaml` with a text editor and find the `plando_options` key. The available plando modules can be enabled by adding them after this such as `plando_options: bosses, items, texts, connections`. -* You can add the necessary plando modules for your settings to the `requires` section of your yaml. Doing so will throw an error if the options that you need to generate properly are not enabled to ensure you will get the results you desire. Only enter in the plando modules that you are using here but it should look like: +* You can add the necessary plando modules for your settings to the `requires` section of your YAML. Doing so will throw an error if the options that you need to generate properly are not enabled to ensure you will get the results you desire. Only enter in the plando modules that you are using here but it should look like: ```yaml requires: @@ -27,45 +28,45 @@ enabled (opt-in). ``` ## Item Plando -Item plando allows a player to place an item in a specific location or specific locations, place multiple items into a +Item plando allows a player to place an item in a specific location or specific locations, or place multiple items into a list of specific locations both in their own game or in another player's game. -* The options for item plando are `from_pool`, `world`, `percentage`, `force`, `count`, and either item and location, or items - and locations. +* The options for item plando are `from_pool`, `world`, `percentage`, `force`, `count`, and either `item` and + `location`, or `items` and `locations`. * `from_pool` determines if the item should be taken *from* the item pool or *added* to it. This can be true or false and defaults to true if omitted. * `world` is the target world to place the item in. * It gets ignored if only one world is generated. * Can be a number, name, true, false, null, or a list. False is the default. - * If a number is used it targets that slot or player number in the multiworld. - * If a name is used it will target the world with that player name. - * If set to true it will be any player's world besides your own. - * If set to false it will target your own world. - * If set to null it will target a random world in the multiworld. + * If a number is used, it targets that slot or player number in the multiworld. + * If a name is used, it will target the world with that player name. + * If set to true, it will be any player's world besides your own. + * If set to false, it will target your own world. + * If set to null, it will target a random world in the multiworld. * If a list of names is used, it will target the games with the player names specified. - * `force` determines whether the generator will fail if the item can't be placed in the location can be true, false, + * `force` determines whether the generator will fail if the item can't be placed in the location. Can be true, false, or silent. Silent is the default. - * If set to true the item must be placed and the generator will throw an error if it is unable to do so. - * If set to false the generator will log a warning if the placement can't be done but will still generate. - * If set to silent and the placement fails it will be ignored entirely. + * If set to true, the item must be placed and the generator will throw an error if it is unable to do so. + * If set to false, the generator will log a warning if the placement can't be done but will still generate. + * If set to silent and the placement fails, it will be ignored entirely. * `percentage` is the percentage chance for the relevant block to trigger. This can be any value from 0 to 100 and if omitted will default to 100. * Single Placement is when you use a plando block to place a single item at a single location. * `item` is the item you would like to place and `location` is the location to place it. * Multi Placement uses a plando block to place multiple items in multiple locations until either list is exhausted. - * `items` defines the items to use and a number letting you place multiple of it. You can use true instead of a number to have it use however many of that item are in your item pool. + * `items` defines the items to use, each with a number for the amount. Using `true` instead of a number uses however many of that item are in your item pool. * `locations` is a list of possible locations those items can be placed in. * Using the multi placement method, placements are picked randomly. - * Instead of a number, you can use true + * `count` can be used to set the maximum number of items placed from the block. The default is 1 if using `item` and False if using `items` - * If a number is used it will try to place this number of items. - * If set to false it will try to place as many items from the block as it can. - * If `min` and `max` are defined, it will try to place a number of items between these two numbers at random + * If a number is used, it will try to place this number of items. + * If set to false, it will try to place as many items from the block as it can. + * If `min` and `max` are defined, it will try to place a number of items between these two numbers at random. ### Available Items and Locations -A list of all available items and locations can be found in the [website's datapackage](/datapackage). The items and locations will be in the `"item_name_to_id"` and `"location_name_to_id"` sections of the relevant game. You do not need the quotes but the name must be entered in the same as it appears on that page and is caps-sensitive. +A list of all available items and locations can be found in the [website's datapackage](/datapackage). The items and locations will be in the `"item_name_to_id"` and `"location_name_to_id"` sections of the relevant game. You do not need the quotes but the name must be entered in the same as it appears on that page and is case-sensitive. ### Examples @@ -142,43 +143,43 @@ plando_items: min: 1 max: 4 ``` -1. This block has a 50% chance to occur, and if it does will place either the Empire Orb or Radiant Orb on another player's -Starter Chest 1 and removes the chosen item from the item pool. +1. This block has a 50% chance to occur, and if it does, it will place either the Empire Orb or Radiant Orb on another +player's Starter Chest 1 and removes the chosen item from the item pool. 2. This block will always trigger and will place the player's swords, bow, magic meter, strength upgrades, and hookshots in their own dungeon major item chests. 3. This block will always trigger and will lock boss relics on the bosses. -4. This block has an 80% chance of occurring and when it does will place all but 1 of the items randomly among the four -locations chosen here. +4. This block has an 80% chance of occurring, and when it does, it will place all but 1 of the items randomly among the +four locations chosen here. 5. This block will always trigger and will attempt to place a random 2 of Levitate, Revealer and Energize into other players' Master Sword Pedestals or Boss Relic 1 locations. 6. This block will always trigger and will attempt to place a random number, between 1 and 4, of progressive swords -into any locations within the game slots named BobsSlaytheSpire and BobsRogueLegacy +into any locations within the game slots named BobsSlaytheSpire and BobsRogueLegacy. ## Boss Plando -As this is currently only supported by A Link to the Past instead of explaining here please refer to the +As this is currently only supported by A Link to the Past, instead of finding an explanation here, please refer to the relevant guide: [A Link to the Past Plando Guide](/tutorial/A%20Link%20to%20the%20Past/plando/en) ## Text Plando -As this is currently only supported by A Link to the Past instead of explaining here please refer to the +As this is currently only supported by A Link to the Past, instead of finding an explanation here, please refer to the relevant guide: [A Link to the Past Plando Guide](/tutorial/A%20Link%20to%20the%20Past/plando/en) ## Connections Plando This is currently only supported by Minecraft and A Link to the Past. As the way that these games interact with their -connections is different I will only explain the basics here while more specifics for Link to the Past connection plando -can be found in its plando guide. +connections is different, I will only explain the basics here, while more specifics for A Link to the Past connection +plando can be found in its plando guide. -* The options for connections are `percentage`, `entrance`, `exit`, and `direction`. Each of these options support +* The options for connections are `percentage`, `entrance`, `exit`, and `direction`. Each of these options supports subweights. * `percentage` is the percentage chance for this connection from 0 to 100 and defaults to 100. * Every connection has an `entrance` and an `exit`. These can be unlinked like in A Link to the Past insanity entrance shuffle. * `direction` can be `both`, `entrance`, or `exit` and determines in which direction this connection will operate. -[Link to the Past connections](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/alttp/EntranceShuffle.py#L3852) +[A Link to the Past connections](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/alttp/EntranceShuffle.py#L3852) [Minecraft connections](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/minecraft/Regions.py#L62) @@ -186,7 +187,7 @@ can be found in its plando guide. ```yaml plando_connections: - # example block 1 - Link to the Past + # example block 1 - A Link to the Past - entrance: Cave Shop (Lake Hylia) exit: Cave 45 direction: entrance @@ -206,9 +207,9 @@ plando_connections: direction: both ``` -1. These connections are decoupled so going into the lake hylia cave shop will take you to the inside of cave 45 and - when you leave the interior you will exit to the cave 45 ledge. Going into the cave 45 entrance will then take you to - the lake hylia cave shop. Walking into the entrance for the old man cave and Agahnim's Tower entrance will both take - you to their locations as normal but leaving old man cave will exit at Agahnim's Tower. -2. This will force a nether fortress and a village to be the overworld structures for your game. Note that for the +1. These connections are decoupled, so going into the Lake Hylia Cave Shop will take you to the inside of Cave 45, and + when you leave the interior, you will exit to the Cave 45 ledge. Going into the Cave 45 entrance will then take you to + the Lake Hylia Cave Shop. Walking into the entrance for the Old Man Cave and Agahnim's Tower entrance will both take + you to their locations as normal, but leaving Old Man Cave will exit at Agahnim's Tower. +2. This will force a Nether fortress and a village to be the Overworld structures for your game. Note that for the Minecraft connection plando to work structure shuffle must be enabled. diff --git a/worlds/generic/docs/triggers_en.md b/worlds/generic/docs/triggers_en.md index 03ce9c65..a9ffebb4 100644 --- a/worlds/generic/docs/triggers_en.md +++ b/worlds/generic/docs/triggers_en.md @@ -8,36 +8,31 @@ about 5 minutes to read. Triggers allow you to customize your game settings by allowing you to define one or many options which only occur under specific conditions. These are essentially "if, then" statements for options in your game. A good example of what you -can do with triggers is the custom mercenary mode YAML that was created using entirely triggers and plando. +can do with triggers is the [custom mercenary mode YAML +](https://github.com/alwaysintreble/Archipelago-yaml-dump/blob/main/Snippets/Mercenary%20Mode%20Snippet.yaml) that was +created using entirely triggers and plando. -Mercenary mode -YAML: [Mercenary Mode YAML on GitHub](https://github.com/alwaysintreble/Archipelago-yaml-dump/blob/main/Snippets/Mercenary%20Mode%20Snippet.yaml) - -For more information on plando you can reference the general plando guide or the Link to the Past plando guide. - -General plando guide: [Archipelago Plando Guide](/tutorial/Archipelago/plando/en) - -Link to the Past plando guide: [LttP Plando Guide](/tutorial/A%20Link%20to%20the%20Past/plando/en) +For more information on plando, you can reference the [general plando guide](/tutorial/Archipelago/plando/en) or the +[A Link to the Past plando guide](/tutorial/A%20Link%20to%20the%20Past/plando/en). ## Trigger use -Triggers may be defined in either the root or in the relevant game sections. Generally, The best place to do this is the -bottom of the yaml for clear organization. +Triggers may be defined in either the root or in the relevant game sections. Generally, the best place to do this is the +bottom of the YAML for clear organization. -- Triggers comprise the trigger section and then each trigger must have an `option_category`, `option_name`, and - `option_result` from which it will react to and then an `options` section for the definition of what will happen. -- `option_category` is the defining section from which the option is defined in. +Each trigger consists of four parts: +- `option_category` specifies the section which the triggering option is defined in. - Example: `A Link to the Past` - - This is the root category the option is located in. If the option you're triggering off of is in root then you + - This is the category the option is located in. If the option you're triggering off of is in root then you would use `null`, otherwise this is the game for which you want this option trigger to activate. -- `option_name` is the option setting from which the triggered choice is going to react to. +- `option_name` specifies the name of the triggering option. - Example: `shop_item_slots` - - This can be any option from any category defined in the yaml file in either root or a game section. -- `option_result` is the result of this option setting from which you would like to react. + - This can be any option from any category defined in the YAML file in either root or a game section. +- `option_result` specifies the value of the option that activates this trigger. - Example: `15` - Each trigger must be used for exactly one option result. If you would like the same thing to occur with multiple - results you would need multiple triggers for this. -- `options` is where you define what will happen when this is detected. This can be something as simple as ensuring + results, you would need multiple triggers for this. +- `options` is where you define what will happen when the trigger activates. This can be something as simple as ensuring another option also gets selected or placing an item in a certain location. It is possible to have multiple things happen in this section. - Example: @@ -47,10 +42,10 @@ bottom of the yaml for clear organization. Rupees (300): 2 ``` -This format must be: +The general format is: ```yaml - root option: + category: option to change: desired result ``` @@ -70,8 +65,8 @@ The above examples all together will end up looking like this: Rupees(300): 2 ``` -For this example if the generator happens to roll 15 shuffled in shop item slots for your game you'll be granted 600 -rupees at the beginning. These can also be used to change other options. +For this example, if the generator happens to roll 15 shuffled in shop item slots for your game, you'll be granted 600 +rupees at the beginning. Triggers can also be used to change other options. For example: @@ -85,9 +80,9 @@ For example: Inverted: true ``` -In this example if your world happens to roll SpecificKeycards then your game will also start in inverted. +In this example, if your world happens to roll SpecificKeycards, then your game will also start in inverted. -It is also possible to use imaginary names in options to trigger specific settings. You can use these made up names in +It is also possible to use imaginary values in options to trigger specific settings. You can use these made-up values in either your main options or to trigger from another trigger. Currently, this is the only way to trigger on "setting 1 AND setting 2". @@ -97,33 +92,33 @@ For example: triggers: - option_category: Secret of Evermore option_name: doggomizer - option_result: pupdunk - options: - Secret of Evermore: - difficulty: - normal: 50 - pupdunk_hard: 25 - pupdunk_mystery: 25 - exp_modifier: - 150: 50 - 200: 50 - - option_category: Secret of Evermore - option_name: difficulty - option_result: pupdunk_hard - options: - Secret of Evermore: - fix_wings_glitch: false - difficulty: hard - - option_category: Secret of Evermore - option_name: difficulty - option_result: pupdunk_mystery - options: - Secret of Evermore: - fix_wings_glitch: false - difficulty: mystery + option_result: pupdunk + options: + Secret of Evermore: + difficulty: + normal: 50 + pupdunk_hard: 25 + pupdunk_mystery: 25 + exp_modifier: + 150: 50 + 200: 50 + - option_category: Secret of Evermore + option_name: difficulty + option_result: pupdunk_hard + options: + Secret of Evermore: + fix_wings_glitch: false + difficulty: hard + - option_category: Secret of Evermore + option_name: difficulty + option_result: pupdunk_mystery + options: + Secret of Evermore: + fix_wings_glitch: false + difficulty: mystery ``` -In this example (thanks to @Black-Sliver) if the `pupdunk` option is rolled then the difficulty values will be rolled +In this example (thanks to @Black-Sliver), if the `pupdunk` option is rolled, then the difficulty values will be rolled again using the new options `normal`, `pupdunk_hard`, and `pupdunk_mystery`, and the exp modifier will be rerolled using new weights for 150 and 200. This allows for two more triggers that will only be used for the new `pupdunk_hard` and `pupdunk_mystery` options so that they will only be triggered on "pupdunk AND hard/mystery". \ No newline at end of file