morgan/Grinch-AP
1
0
Fork 0
mirror of https://github.com/MarioSpore/Grinch-AP.git synced 2025-10-21 12:11:33 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Update Plando Guide and Make it More User Friendly (#4858)

Browse Source 
* 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>
This commit is contained in:
massimilianodelliubaldini
2025-06-16 12:54:08 -04:00
committed by GitHub
parent 47bf6d724b
commit 6f244c4661
1 changed files with 156 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
worlds/generic/docs/plando_en.md
View File

@@ -27,73 +27,176 @@ requires:
plando: bosses, items, texts, connections 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
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 Item Plando allows a player to place an item in a specific location or locations, or place multiple items into a list
`location`, or `items` and `locations`. of specific locations in their own game and/or in another player's game.
* `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.
* `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` To add item plando to your player yaml, you add them under the `plando_items` block. You should start with `item` if you
* If a number is used, it will try to place this number of items. want to do Single Placement, or `items` if you want to do Multi Placement. A list of items can still be defined under
* If set to false, it will try to place as many items from the block as it can. `item` but only one of them will be chosen at random to be used.
* If `min` and `max` are defined, it will try to place a number of items between these two numbers at random.
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 ### 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 ```yaml
plando_items: 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: - item:
Empire Orb: 1 Empire Orb: 1
Radiant Orb: 1 Radiant Orb: 3
location: Starter Chest 1 location: Starter Chest 1
from_pool: true from_pool: false
world: true world: true
percentage: 50 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: - items:
Kokiri Sword: 1
Biggoron Sword: 1 Biggoron Sword: 1
Bow: 1 Bow: 1
Magic Meter: 1 Magic Meter: 1
Progressive Strength Upgrade: 3 Progressive Strength Upgrade: 3
Progressive Hookshot: 2 Progressive Hookshot: 2
locations: locations:
- Deku Tree Slingshot Chest
- Dodongos Cavern Bomb Bag Chest - Dodongos Cavern Bomb Bag Chest
- Jabu Jabus Belly Boomerang Chest - Jabu Jabus Belly Boomerang Chest
- Bottom of the Well Lens of Truth 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 - Water Temple Longshot Chest
- Shadow Temple Hover Boots Chest - Shadow Temple Hover Boots Chest
- Spirit Temple Silver Gauntlets Chest - Spirit Temple Silver Gauntlets Chest
world: false from_pool: false
# example block 3 - Factorio - item: Kokiri Sword
- items: location: Deku Tree Slingshot Chest
progressive-electric-energy-distribution: 2 from_pool: false
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
``` ```
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 The first block will place the player's Biggoron Sword, Bow, Magic Meter, strength upgrades, and hookshots in the
player's Starter Chest 1 and removes the chosen item from the item pool. dungeon major item chests. Because the from_pool value is `false`, a copy of these items is added to these locations,
2. This block will always trigger and will place the player's swords, bow, magic meter, strength upgrades, and hookshots while the originals remain in the item pool to be shuffled. The second block will place the Kokiri Sword in the Deku
in their own dungeon major item chests. Tree Slingshot Chest, again not from the pool.
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.
## Boss Plando ## Boss Plando