monorail
/
Archipelago
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: Update YAML planning guide (#1845) 

* [Docs] Update YAML planning guide

Changed wording for items accessibility to describe how it actually works. Reordered settings such as local_items and start_location_hints to match their order in templates. Fixed some grammatical errors.

* Fix typo

Co-authored-by: Zach Parks <zach@alliware.com>

* Update doc

Moved `accessibility`, `progression_balancing`, and `triggers` to game sections instead of root sections and reworded description accordingly. Updated version number. Fixed `progression_balancing` values in example YAMLs.

* Indented trigger to be part of ALTTP

---------

Co-authored-by: Zach Parks <zach@alliware.com>
This commit is contained in:
Exempt-Medic 2023-06-01 23:33:12 -04:00 committed by GitHub
parent 5401e485aa
commit b98080afee
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 99 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
worlds/generic/docs/advanced_settings_en.md
View File

@ -1,15 +1,18 @@
# Advanced YAML Guide
This guide covers more the more advanced options available in YAML files. This guide is intended for the user who plans
to edit their YAML file manually. This guide should take about 10 minutes to read.
This guide covers more the more advanced options available in YAML files. This guide is intended for the user who is intent on editing their YAML file manually. This guide should take about 10 minutes to read.
If you would like to generate a basic, fully playable YAML without editing a file, then visit the settings page for the
game you intend to play. The weighted settings page can also handle most of the advanced settings discussed here.
If you would like to generate a basic, fully playable, YAML without editing a file then visit the settings page for the game you intend to play. The weighted settings page can also handle most of the advanced settings discussed here.
The settings page can be found on the supported games page, just click the "Settings Page" link under the name of the game you would like.
The settings page can be found on the supported games page, just click the "Settings Page" link under the name of the
game you would like.
* Supported games page: [Archipelago Games List](/games)
* Weighted settings page: [Archipelago Weighted Settings](/weighted-settings)
Clicking on the "Export Settings" button at the bottom-left will provide you with a pre-filled YAML with your options.
The player settings page also has a link to download a full template file for that game which will have every option possible for the game including some that don't display correctly on the site.
The player settings page also has a link to download a full template file for that game which will have every option
possible for the game including some that don't display correctly on the site.
## YAML Overview
@ -42,8 +45,8 @@ root_option:
```
In Archipelago, YAML options are always written out in full lowercase with underscores separating any words. The numbers
following the colons here are weights. The generator will read the weight of every option the roll that option that many
times, the next option as many times as its numbered and so forth.
following the colons here are weights. The generator will read the weight of every option, then roll that option that
many times, the next option as many times as its numbered and so forth.
For the above example `nested_option_one` will have `option_one_setting_one` 1 time and `option_one_setting_two` 0 times
so `option_one_setting_one` is guaranteed to occur.
@ -56,8 +59,7 @@ adding more randomness and "mystery" to your settings. Every configurable settin
Currently, there are only a few options that are root options. Everything else should be nested within one of these root
options or in some cases nested within other nested options. The only options that should exist in root
are `description`, `name`, `game`, `requires`, `accessibility`, `progression_balancing`, `triggers`, and the name of the
games you want settings for.
are `description`, `name`, `game`, `requires`, and the name of the games you want settings for.
* `description` is ignored by the generator and is simply a good way for you to organize if you have multiple files
using this to detail the intention of the file.
@ -72,40 +74,18 @@ games you want settings for.
* `{NUMBER}` will be replaced with the counter value of the name if the counter value is greater than 1, otherwise
blank.
* `game` is where either your chosen game goes or if you would like can be filled with multiple games each with
* `game` is where either your chosen game goes or, if you would like, can be filled with multiple games each with
different weights.
* `requires` details different requirements from the generator for the YAML to work as you expect it to. Generally this
is good for detailing the version of Archipelago this YAML was prepared for as if it is rolled on an older version may
be missing settings and as such will not work as expected. If any plando is used in the file then requiring it here to
ensure it will be used is good practice.
* `accessibility` determines the level of access to the game the generation will expect you to have in order to reach
your completion goal. This supports `items`, `locations`, and `none` and is set to `locations` by default.
* `locations` will guarantee all locations are accessible in your world.
* `items` will guarantee you can acquire all items in your world but may not be able to access all locations. This
mostly comes into play if there is any entrance shuffle in the seed as locations without items in them can be
placed in areas that make them unreachable.
* `none` will only guarantee that the seed is beatable. You will be guaranteed able to finish the seed logically but
may not be able to access all locations or acquire all items. A good example of this is having a big key in the
big chest in a dungeon in ALTTP making it impossible to get and finish the dungeon.
* `progression_balancing` is a system the Archipelago generator uses to try and reduce "BK mode" as much as possible.
This primarily involves moving necessary progression items into earlier logic spheres to make the games more
accessible so that players almost always have something to do. This can be in a range from 0 to 99, and is 50 by
default. This number represents a percentage of the furthest progressible player.
* For example: With the default of 50%, if the furthest player can access 40% of their items, the randomizer tries
to let you access at least 20% of your items. 50% of 40% is 20%.
* Note that it is not always guaranteed that it will be able to bring you up to this threshold.
* `triggers` is one of the more advanced options that allows you to create conditional adjustments. You can read
more triggers in the triggers guide. Triggers
guide: [Archipelago Triggers Guide](/tutorial/Archipelago/triggers/en)
is good for detailing the version of Archipelago this YAML was prepared for as, if it is rolled on an older version,
settings may be missing and as such it will not work as expected. If any plando is used in the file then requiring it
here to ensure it will be used is good practice.
## Game Options
One of your root settings will be the name of the game you would like to populate with settings. Since it is possible to
give a weight to any option it is possible to have one file that can generate a seed for you where you don't know which
give a weight to any option, it is possible to have one file that can generate a seed for you where you don't know which
game you'll play. For these cases you'll want to fill the game options for every game that can be rolled by these
settings. If a game can be rolled it **must** have a settings section even if it is empty.
@ -113,26 +93,50 @@ settings. If a game can be rolled it **must** have a settings section even if it
Some options in Archipelago can be used by every game but must still be placed within the relevant game's section.
Currently, these options are `start_inventory`, `start_hints`, `local_items`, `non_local_items`, `start_location_hints`
, `exclude_locations`, and various plando options.
Currently, these options are `accessibility`, `progression_balancing`, `triggers`, `local_items`, `non_local_items`,
`start_inventory`, `start_hints`, `start_location_hints`, `exclude_locations`, `priority_locations`, `item_links`, and
various plando options.
See the plando guide for more info on plando options. Plando
guide: [Archipelago Plando Guide](/tutorial/Archipelago/plando/en)
* `accessibility` determines the level of access to the game the generation will expect you to have in order to reach
your completion goal. This supports `items`, `locations`, and `minimal` and is set to `locations` by default.
* `locations` will guarantee all locations are accessible in your world.
* `items` will guarantee you can acquire all logically relevant items in your world. Some items, such as keys, may
be self-locking.
* `minimal` will only guarantee that the seed is beatable. You will be guaranteed able to finish the seed logically
but may not be able to access all locations or acquire all items. A good example of this is having a big key in
the big chest in a dungeon in ALTTP making it impossible to get and finish the dungeon.
* `progression_balancing` is a system the Archipelago generator uses to try and reduce "BK mode" as much as possible.
This primarily involves moving necessary progression items into earlier logic spheres to make the games more
accessible so that players almost always have something to do. This can be in a range from 0 to 99, and is 50 by
default. This number represents a percentage of the furthest progressible player.
* For example: With the default of 50%, if the furthest player can access 40% of their items, the randomizer tries
to let you access at least 20% of your items. 50% of 40% is 20%.
* Note that it is not always guaranteed that it will be able to bring you up to this threshold.
* `triggers` is one of the more advanced options that allows you to create conditional adjustments. You can read
more triggers in the triggers guide. Triggers
guide: [Archipelago Triggers Guide](/tutorial/Archipelago/triggers/en)
* `local_items` will force any items you want to be in your world instead of being in another world.
* `non_local_items` is the inverse of `local_items`, forcing any items you want to be in another world instead of
your own.
* `start_inventory` will give any items defined here to you at the beginning of your game. The format for this must be
the name as it appears in the game files and the amount you would like to start with. For example `Rupees(5): 6` which
will give you 30 rupees.
* `start_hints` gives you free server hints for the defined item/s at the beginning of the game allowing you to hint for
* `start_hints` gives you free server hints for the defined items at the beginning of the game, allowing you to hint for
the location without using any hint points.
* `local_items` will force any items you want to be in your world instead of being in another world.
* `non_local_items` is the inverse of `local_items` forcing any items you want to be in another world and won't be
located in your own.
* `start_location_hints` allows you to define a location which you can then hint for to find out what item is located in
it to see how important the location is.
* `start_location_hints` is the same as `start_hints` but for locations, allowing you to hint for the item contained
there without using any hint points.
* `exclude_locations` lets you define any locations that you don't want to do and during generation will force a "junk"
item which isn't necessary for progression to go in these locations.
* `item_links` allows players to link their items into a group with the same item link name and game. The items declared in `item_pool` get combined and when an item is found for the group, all players in the group receive it. Item links can also have local and non local items, forcing the items to either be placed within the worlds of the group or in worlds outside the group. If players have a varying amount of a specific item in the link, the lowest amount from the players will be the amount put into the group.
* `priority_locations` is the inverse of `exlcude_locations`, forcing a progression item in the defined locations.
* `item_links` allows players to link their items into a group with the same item link name and game. The items declared
in `item_pool` get combined and when an item is found for the group, all players in the group receive it. Item links
can also have local and non local items, forcing the items to either be placed within the worlds of the group or in
worlds outside the group. If players have a varying amount of a specific item in the link, the lowest amount from the
players will be the amount put into the group.
### Random numbers
Options taking a choice of a number can also use a variety of `random` options to choose a number randomly.
@ -157,10 +161,10 @@ game:
A Link to the Past: 10
Timespinner: 10
requires:
version: 0.3.2
accessibility: none
progression_balancing: on
version: 0.4.1
A Link to the Past:
accessibility: minimal
progression_balancing: 50
smallkey_shuffle:
original_dungeon: 1
any_world: 1
@ -168,23 +172,23 @@ A Link to the Past:
random-low: 1
crystals_needed_for_ganon:
random-range-high-1-7: 1
start_inventory:
Pegasus Boots: 1
Bombs (3): 2
start_hints:
- Hammer
local_items:
- Bombos
- Ether
- Quake
non_local_items:
- Moon Pearl
start_inventory:
Pegasus Boots: 1
Bombs (3): 2
start_hints:
- Hammer
start_location_hints:
- Spike Cave
priority_locations:
- Link's House
exclude_locations:
- Cave 45
priority_locations:
- Link's House
item_links:
- name: rods
item_pool:
@ -192,16 +196,18 @@ A Link to the Past:
- Ice Rod
replacement_item: "Rupee (1)"
link_replacement: true
triggers:
- option_category: A Link to the Past
option_name: smallkey_shuffle
option_result: any_world
options:
A Link to the Past:
bigkey_shuffle: any_world
map_shuffle: any_world
compass_shuffle: any_world
triggers:
- option_category: A Link to the Past
option_name: smallkey_shuffle
option_result: any_world
options:
A Link to the Past:
bigkey_shuffle: any_world
map_shuffle: any_world
compass_shuffle: any_world
Timespinner:
accessibility: minimal
progression_balancing: 50
item_links: # Share part of your item pool with other players.
- name: TSAll
item_pool:
@ -209,8 +215,7 @@ Timespinner:
local_items:
- Twin Pyramid Key
- Timespinner Wheel
replacement_item: null
replacement_item: null
```
#### This is a fully functional yaml file that will do all the following things:
@ -220,10 +225,10 @@ Timespinner:
* `game` has an equal chance of being either `A Link to the Past` or `Timespinner` with a 10/20 chance for each. This is
because each game has a weight of 10 and the total of all weights is 20.
* `requires` is set to required release version 0.3.2 or higher.
* `accessibility` is set to `none` which will set this seed to beatable only, so some locations and items may be
completely inaccessible but the seed will still be completable.
* `progression_balancing` is set on, giving it the default value, meaning we will likely receive important items
earlier increasing the chance of having things to do.
* `accessibility` for both games is set to `minimal` which will set this seed to beatable only, so some locations and
items may be completely inaccessible but the seed will still be completable.
* `progression_balancing` for both games is set to 50, the default value, meaning we will likely receive important items
earlier, increasing the chance of having things to do.
* `A Link to the Past` defines a location for us to nest all the game options we would like to use for our
game `A Link to the Past`.
* `smallkey_shuffle` is an option for A Link to the Past which determines how dungeon small keys are shuffled. In this
@ -234,36 +239,46 @@ Timespinner:
towards a lower number.
* `crystals_needed_for_ganon` determines the number of crystals required to beat Ganon. In this example a number between
1 and 7 will be chosen at random, weighted towards a high number.
* `local_items` forces the `Bombos`, `Ether`, and `Quake` medallions to all be placed within our own world, meaning we
have to find it ourselves.
* `non_local_items` forces the `Moon Pearl` to be placed in someone else's world, meaning we won't be able to find it.
* `start_inventory` defines an area for us to determine what items we would like to start the seed with. For this
example we have:
* `Pegasus Boots: 1` which gives us 1 copy of the Pegasus Boots
* `Bombs (3): 2` gives us 2 packs of 3 bombs or 6 total bombs
* `start_hints` gives us a starting hint for the hammer available at the beginning of the multiworld which we can use
with no cost.
* `local_items` forces the `Bombos`, `Ether`, and `Quake` medallions to all be placed within our own world, meaning we
have to find it ourselves.
* `non_local_items` forces the `Moon Pearl` to be placed in someone else's world, meaning we won't be able to find it.
* `start_location_hints` gives us a starting hint for the `Spike Cave` location available at the beginning of the
multiworld that can be used for no cost.
* `priority_locations` forces a progression item to be placed on the `Link's House` location.
* `exclude_locations` forces a not important item to be placed on the `Cave 45` location.
* `item_links`
* `priority_locations` forces a progression item to be placed on the `Link's House` location.
* `item_links`
* For `A Link to the Past` all players in the `rods` item link group will share their fire and ice rods and the player
items will be replaced with single rupees. The rupee will also be shared among those players.
* For `Timespinner` all players in the `TSAll` item link group will share their entire item pool and the `Twin Pyramid
Key` and `Timespinner Wheel` will be forced among the worlds of those in the group. The `null` replacement item will,
instead of forcing a specific chosen item, allow the generator to randomly pick a filler item to replace the player items.
* For `Timespinner` all players in the `TSAll` item link group will share their entire item pool and the `Twin Pyramid
Key` and `Timespinner Wheel` will be forced among the worlds of those in the group. The `null` replacement item
will, instead of forcing a specific chosen item, allow the generator to randomly pick a filler item to replace the
player items.
* `triggers` allows us to define a trigger such that if our `smallkey_shuffle` option happens to roll the `any_world`
result it will also ensure that `bigkey_shuffle`, `map_shuffle`, and `compass_shuffle` are also forced to the
`any_world` result. More information on triggers can be found in the [triggers guide](/tutorial/Archipelago/triggers/en).
`any_world` result. More information on triggers can be found in the
[triggers guide](/tutorial/Archipelago/triggers/en).
## Generating Multiple Worlds
YAML files can be configured to generate multiple worlds using only one file. This is mostly useful if you are playing an asynchronous multiworld (shortened to async) and are wanting to submit multiple worlds as they can be condensed into one file, removing the need to manage separate files if one chooses to do so.
As a precautionary measure, before submitting a multi-game yaml like this one in a synchronous/sync multiworld, please confirm that the other players in the multi are OK with what you are submitting, and please be fairly reasonable about the submission. (ie. Multiple long games (SMZ3, OoT, HK, etc.) for a game intended to be <2 hrs is not likely considered reasonable, but submitting a ChecksFinder alongside another game OR submitting multiple Slay the Spire runs is likely OK)
YAML files can be configured to generate multiple worlds using only one file. This is mostly useful if you are playing
an asynchronous multiworld (shortened to async) and are wanting to submit multiple worlds as they can be condensed into
one file, removing the need to manage separate files if one chooses to do so.
To configure your file to generate multiple worlds, use 3 dashes `---` on an empty line to separate the ending of one world and the beginning of another world.
As a precautionary measure, before submitting a multi-game yaml like this one in a synchronous/sync multiworld, please
confirm that the other players in the multi are OK with what you are submitting, and please be fairly reasonable about
the submission. (ie. Multiple long games (SMZ3, OoT, HK, etc.) for a game intended to be <2 hrs is not likely considered
reasonable, but submitting a ChecksFinder alongside another game OR submitting multiple Slay the Spire runs is likely
OK)
To configure your file to generate multiple worlds, use 3 dashes `---` on an empty line to separate the ending of one
world and the beginning of another world.
### Example