From 6f244c4661a7aee59f452f61a51e61adb3f856d5 Mon Sep 17 00:00:00 2001 From: massimilianodelliubaldini <8584296+massimilianodelliubaldini@users.noreply.github.com> Date: Mon, 16 Jun 2025 12:54:08 -0400 Subject: [PATCH] Docs: Update Plando Guide and Make it More User Friendly (#4858) * Make plando guide more user friendly. * Apply suggestions from code review Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> * Further updates for review. * Clear search box when filtering by type. * Forget previous commit name - more code review updates to doc. * Move link to yaml tutorial. * Replace STS example with Pokemon RB. * Use non-key item examples in RB. * Rooby's code review updates. * Update worlds/generic/docs/plando_en.md Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> * Update worlds/generic/docs/plando_en.md Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> * Address some more feedback. * Make Factorio example more accurate. * Exempt's code review updates (round 4) * Exempt's code review updates (round 4 + 1) * Update worlds/generic/docs/plando_en.md Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> * Update worlds/generic/docs/plando_en.md Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> * Update worlds/generic/docs/plando_en.md Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> * Update worlds/generic/docs/plando_en.md Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> --------- Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com> --- worlds/generic/docs/plando_en.md | 246 ++++++++++++++++++++----------- 1 file changed, 156 insertions(+), 90 deletions(-) diff --git a/worlds/generic/docs/plando_en.md b/worlds/generic/docs/plando_en.md index b383239d..69f59c73 100644 --- a/worlds/generic/docs/plando_en.md +++ b/worlds/generic/docs/plando_en.md @@ -27,73 +27,176 @@ requires: plando: bosses, items, texts, connections ``` +For a basic understanding of YAML files, refer to +[YAML Formatting](/tutorial/Archipelago/advanced_settings/en#yaml-formatting) +in Advanced Settings. + ## Item Plando -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`. - * `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 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, - 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. - * `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, 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. - * Some special location group names can be specified: - * `early_locations` will add all sphere 1 locations (locations logically reachable only with your starting inventory) - * `non_early_locations` will add all locations beyond sphere 1 (locations that require finding at least one item before they become logically reachable) - * Using the multi placement method, placements are picked randomly. +Item Plando allows a player to place an item in a specific location or locations, or place multiple items into a list +of specific locations in their own game and/or in another player's game. - * `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. +To add item plando to your player yaml, you add them under the `plando_items` block. You should start with `item` if you +want to do Single Placement, or `items` if you want to do Multi Placement. A list of items can still be defined under +`item` but only one of them will be chosen at random to be used. +After you define `item/items`, you would define `location` or `locations`, depending on if you want to fill one +location or many. Note that both `location` and `locations` are optional. A list of locations can still be defined under +`location` but only one of them will be chosen at random to be used. + +You may do any combination of `item/items` and `location/locations` in a plando block, but the block only places items +in locations **until the shorter of the two lists is used up.** + +Once you are satisfied with your first block, you may continue to define ones under the same `plando_items` parent. +Each block can have several different options to tailor it the way you like. + +* The `items` section defines the items to use. Each item name can be followed by a colon and a value. + * A numerical value indicates the amount of that item. + * A `true` value uses all copies of that item that are in your item pool. + +* The `item` section defines a list of items to use, from which one will be chosen at random. Each item name can be + followed by a colon and a value. The value indicates the weight of that item being chosen. + +* The `locations` section defines possible locations those items can be placed in. Two special location groups exist: + * `early_locations` will add all sphere 1 locations (locations logically reachable only with your starting + inventory). + * `non_early_locations` will add all locations beyond sphere 1 (locations that require finding at least one item + before they become logically reachable). + +* `from_pool` determines if the item should be taken *from* the item pool or *created* from scratch. + * `false`: Create a new item with the same name (the world will determine its properties e.g. classification). + * `true`: Take the existing item, if it exists, from the item pool. If it does not exist, one will be created from + scratch. **(Default)** + +* `world` is the target world to place the item in. It gets ignored if only one world is generated. + * **A number:** Use this slot or player number in the multiworld. + * **A name:** Use the world with that player name. + * **A list of names:** Use the worlds with the player names specified. + * `true`: Locations will be in any player's world besides your own. + * `false`: Locations will be in your own world. **(Default)** + * `null`: Locations will be in a random world in the multiworld. + +* `force` determines whether the generator will fail if the plando block cannot be fulfilled. + * `true`: The generator will throw an error if it is unable to place an item. + * `false`: The generator will log a warning if it is unable to place an item, but it will still generate. + * `silent`: If the placement fails, it will be ignored entirely. **(Default)** + +* `percentage` is the percentage chance for the block to trigger. This can be any integer from 0 to 100. + **(Default: 100)** + +* `count` sets the number of items placed from the list. + * **Default: 1 if using `item` or `location`, and `false` otherwise.** + * **A number:** It will place this number of items. + * `false`: It will place as many items from the list as it can. + * **If `min` is defined,** it will place at least `min` many items (can be combined with `max`). + * **If `max` is defined,** it will place at most `max` many items (can be combined with `min`). ### 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 case-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. Names are +case-sensitive. You can also use item groups and location groups that are defined in the datapackage. -### Examples +## Item Plando Examples +```yaml + plando_items: + # Example block - Pokémon Red and Blue + - items: + Potion: 3 + locations: + - "Route 1 - Free Sample Man" + - "Mt Moon 1F - West Item" + - "Mt Moon 1F - South Item" +``` +This block will lock 3 Potion items on the Route 1 Pokémart employee and 2 Mt Moon items. Note these are all +Potions in the vanilla game. The world value has not been specified, so these locations must be in this player's own +world by default. ```yaml plando_items: - # example block 1 - Timespinner + # Example block - A Link to the Past + - items: + Progressive Sword: 4 + world: + - BobsWitness + - BobsRogueLegacy + count: + min: 1 + max: 4 +``` +This block will attempt to place a random number, between 1 and 4, of Progressive Swords into any locations within the +game slots named "BobsWitness" and "BobsRogueLegacy." + +```yaml + plando_items: + # Example block - Secret of Evermore + - items: + Levitate: 1 + Revealer: 1 + Energize: 1 + locations: + - Master Sword Pedestal + - Desert Discard + world: true + count: 2 +``` +This block will choose 2 from the Levitate, Revealer, and Energize items at random and attempt to put them into the +locations named "Master Sword Pedestal" and "Desert Discard". Because the world value is `true`, these locations +must be in other players' worlds. + +```yaml + plando_items: + # Example block - Timespinner - item: Empire Orb: 1 - Radiant Orb: 1 + Radiant Orb: 3 location: Starter Chest 1 - from_pool: true + from_pool: false world: true percentage: 50 - - # example block 2 - Ocarina of Time +``` +This block will place a single item, either the Empire Orb or Radiant Orb, on the location "Starter Chest 1". There is +a 25% chance it is Empire Orb, and 75% chance it is Radiant Orb (1 to 3 odds). The world value is `true`, so this +location must be in another player's world. Because the from_pool value is `false`, a copy of these items is added to +these locations, while the originals remain in the item pool to be shuffled. Unlike the previous examples, which will +always trigger, this block only has a 50% chance to trigger. + +```yaml + plando_items: + # Example block - Factorio + - items: + progressive-electric-energy-distribution: 2 + electric-energy-accumulators: 1 + progressive-turret: 2 + locations: + - AP-1-001 + - AP-1-002 + - AP-1-003 + - AP-1-004 + percentage: 80 + force: true + from_pool: true + world: false +``` +This block lists 5 items but only 4 locations, so it will place all but 1 of the items randomly among the locations +chosen here. This block has an 80% chance of occurring. Because force is `true`, the Generator will fail if it cannot +place one of the selected items (not including the fifth item). From_pool and World have been set to their default +values here, but they can be omitted and have the same result: items will be removed from the pool, and the locations +are in this player's own world. + +**NOTE:** Factorio's locations are dynamically generated, so the locations listed above may not exist in your game, +they are here for demonstration only. + +```yaml + plando_items: + # Example block - Ocarina of Time - items: - Kokiri Sword: 1 Biggoron Sword: 1 Bow: 1 Magic Meter: 1 Progressive Strength Upgrade: 3 Progressive Hookshot: 2 locations: - - Deku Tree Slingshot Chest - Dodongos Cavern Bomb Bag Chest - Jabu Jabus Belly Boomerang Chest - Bottom of the Well Lens of Truth Chest @@ -102,53 +205,16 @@ A list of all available items and locations can be found in the [website's datap - Water Temple Longshot Chest - Shadow Temple Hover Boots Chest - Spirit Temple Silver Gauntlets Chest - world: false - - # example block 3 - Factorio - - items: - progressive-electric-energy-distribution: 2 - electric-energy-accumulators: 1 - progressive-turret: 2 - locations: - - military - - gun-turret - - logistic-science-pack - - steel-processing - percentage: 80 - force: true - - # example block 4 - Secret of Evermore - - items: - Levitate: 1 - Revealer: 1 - Energize: 1 - locations: - - Master Sword Pedestal - - Boss Relic 1 - world: true - count: 2 - - # example block 5 - A Link to the Past - - items: - Progressive Sword: 4 - world: - - BobsSlaytheSpire - - BobsRogueLegacy - count: - min: 1 - max: 4 + from_pool: false + + - item: Kokiri Sword + location: Deku Tree Slingshot Chest + from_pool: false ``` -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 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. -4. 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. -5. 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. - +The first block will place the player's Biggoron Sword, Bow, Magic Meter, strength upgrades, and hookshots in the +dungeon major item chests. Because the from_pool value is `false`, a copy of these items is added to these locations, +while the originals remain in the item pool to be shuffled. The second block will place the Kokiri Sword in the Deku +Tree Slingshot Chest, again not from the pool. ## Boss Plando