Grinch-AP/worlds/generic/docs/plando_en.md

Archipelago Plando Guide

What is Plando?

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 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 enabled (opt-in).

• 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:

requires: 
  version: current.version.number
  plando: bosses, items, texts, connections

For a basic understanding of YAML files, refer to YAML Formatting in Advanced Settings.

Item Plando

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.

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. 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.

Item Plando Examples

 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.

  plando_items:
  # 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."

  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.

  plando_items:
    # Example block - Timespinner
    - item:
        Empire Orb: 1
        Radiant Orb: 3
      location: Starter Chest 1
      from_pool: false
      world: true
      percentage: 50

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.

  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.

  plando_items:
    # Example block - Ocarina of Time
    - items:
        Biggoron Sword: 1
        Bow: 1
        Magic Meter: 1
        Progressive Strength Upgrade: 3
        Progressive Hookshot: 2
      locations:
        - Dodongos Cavern Bomb Bag Chest
        - Jabu Jabus Belly Boomerang Chest
        - Bottom of the Well Lens of Truth Chest
        - Forest Temple Bow Chest
        - Fire Temple Megaton Hammer Chest
        - Water Temple Longshot Chest
        - Shadow Temple Hover Boots Chest
        - Spirit Temple Silver Gauntlets Chest
      from_pool: false
      
    - item: Kokiri Sword
      location: Deku Tree Slingshot Chest
      from_pool: false

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

This is currently only supported by A Link to the Past and Kirby's Dream Land 3. Boss plando allows a player to place a given boss within an arena. More specific information for boss plando in A Link to the Past can be found in its plando guide.

Boss plando takes in a list of instructions for placing bosses, separated by a semicolon ;. There are three types of placement: direct, full, and shuffle.

• Direct placement takes both an arena and a boss, and places the boss into that arena.
  • Eastern Palace-Trinexx
• Full placement will take a boss, and place it into as many remaining arenas as possible.
  • King Dedede
• Shuffle will fill any remaining arenas using a given boss shuffle option, typically to be used as the last instruction.
  • full

Examples

A Link to the Past:
  boss_shuffle:
    # Basic boss shuffle, but prevent Trinexx from being outside Turtle Rock
    Turtle Rock-Trinexx;basic: 1
    # Place as many Arrghus as possible, then let the rest be random
    Arrghus;chaos: 1
    
Kirby's Dream Land 3:
  boss_shuffle:
    # Ensure Iceberg's boss will be King Dedede, but randomize the rest
    Iceberg-King Dedede;full: 1
    # Have all bosses be Whispy Woods
    Whispy Woods: 1
    # Ensure Ripple Field's boss is Pon & Con, but let the method others
    # are placed with be random
    Ripple Field-Pon & Con;random: 1

Text Plando

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

Connection Plando

This is currently only supported by a few games, including A Link to the Past and Ocarina of Time. As the way that these games interact with their connections is different, only the basics are explained here. More specific information for connection plando in A Link to the Past can be found in its plando guide.

• 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. direction defaults to both.

A Link to the Past connections

Examples

  plando_connections:
    # example block 1 - A Link to the Past
    - entrance: Cave Shop (Lake Hylia)
      exit: Cave 45
      direction: entrance
    - entrance: Cave 45
      exit: Cave Shop (Lake Hylia)
      direction: entrance
    - entrance: Agahnims Tower
      exit: Old Man Cave Exit (West)
      direction: exit

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.