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

Webworld docs: move gameinfo documentation to their world folders and copy them for webhost use. (#455)

Browse Source
This commit is contained in:
alwaysintreble
2022-05-11 13:05:53 -05:00
committed by GitHub
parent 9e15e754c2
commit 977159e572
91 changed files with 537 additions and 703 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
worlds/generic/docs/advanced_settings_en.md Normal file
View File

@@ -0,0 +1,234 @@
# Advanced YAML Guide
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.
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.
## YAML Overview
The Archipelago system generates games using player configuration files as input. These are going to be YAML files and
each world will have one of these containing their custom settings for the game that world will play.
## YAML Formatting
YAML files are a format of human-readable config files. The basic syntax of a yaml file will have a `root` node and then
different levels of `nested` nodes that the generator reads in order to determine your settings.
To nest text, the correct syntax is to indent **two spaces over** from its root option. A YAML file can be edited with
whatever text editor you choose to use though I personally recommend that you use Sublime Text. Sublime text
website: [SublimeText Website](https://www.sublimetext.com)
This program out of the box supports the correct formatting for the YAML file, so you will be able to use the tab key
and get proper highlighting for any potential errors made while editing the file. If using any other text editor you
should ensure your indentation is done correctly with two spaces.
A typical YAML file will look like:
```yaml
root_option:
nested_option_one:
option_one_setting_one: 1
option_one_setting_two: 0
nested_option_two:
option_two_setting_one: 14
option_two_setting_two: 43
```
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.
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.
For `nested_option_two`, `option_two_setting_one` will be rolled 14 times and `option_two_setting_two` will be rolled 43
times against each other. This means `option_two_setting_two` will be more likely to occur, but it isn't guaranteed,
adding more randomness and "mystery" to your settings. Every configurable setting supports weights.
### Root Options
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.
* `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.
* `name` is the player name you would like to use and is used for your slot data to connect with most games. This can
also be filled with multiple names each having a weight to it.
* `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)
### 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
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.
#### Universal Game Options
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.
See the plando guide for more info on plando options. Plando
guide: [Archipelago Plando Guide](/tutorial/Archipelago/plando/en)
* `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
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.
* `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 you to link up items so that when one players finds the item all other participating players also
get it.
### Random numbers
Options taking a choice of a number can also use a variety of `random` options to choose a number randomly.
* `random` will choose a number allowed for the setting at random
* `random-low` will choose a number allowed for the setting at random, but will be weighted towards lower numbers
* `random-middle` will choose a number allowed for the setting at random, but will be weighted towards the middle of the
range
* `random-high` will choose a number allowed for the setting at random, but will be weighted towards higher numbers
* `random-range-#-#` will choose a number at random from between the specified numbers. For example `random-range-40-60`
will choose a number between 40 and 60
* `random-range-low-#-#`, `random-range-middle-#-#`, and `random-range-high-#-#` will choose a number at random from the
specified numbers, but with the specified weights
### Example
```yaml
description: An example using various advanced options
name: Example Player
game: A Link to the Past
requires:
version: 0.2.0
accessibility: none
progression_balancing: on
A Link to the Past:
smallkey_shuffle:
original_dungeon: 1
any_world: 1
crystals_needed_for_gt:
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_location_hints:
- Spike Cave
exclude_locations:
- Cave 45
item_links:
- name: rods
item_pool:
- Fire Rod
- Ice Rod
replacement_item: "Rupee (1)"
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
```
#### This is a fully functional yaml file that will do all the following things:
* `description` gives us a general overview so if we pull up this file later we can understand the intent.
* `name` is `Example Player` and this will be used in the server console when sending and receiving items.
* `game` is set to `A Link to the Past` meaning that is what game we will play with this file.
* `requires` is set to require release version 0.2.0 or higher.
* `accesibility` is set to `none` which will set this seed to beatable only meaning 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.
* `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
example we have a 1/2 chance for them to either be placed in their original dungeon and a 1/2 chance for them to be
placed anywhere amongst the multiworld.
* `crystals_needed_for_gt` determines the number of crystals required to enter the Ganon's Tower entrance. In this
example a random number will be chosen from the allowed range for this setting (0 through 7) but will be weighted
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.
* `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)` 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.
* `exclude_locations` forces a not important item to be placed on the `Cave 45` location.
* `item_links` causes all players with the same `item_links` settings to share a `Fire Rod` and `Ice Rod`. Extra
`Rupee (1)` are put in the item pool instead of additional Rods.
* `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.

96
worlds/generic/docs/commands_en.md Normal file
View File

@@ -0,0 +1,96 @@
### Helpful Commands
Commands are split into two types: client commands and server commands. Client commands are commands which are executed
by the client and do not affect the Archipelago remote session. Server commands are commands which are executed by the
Archipelago server and affect the Archipelago session or otherwise provide feedback from the server.
In clients which have their own commands the commands are typically prepended by a forward slash:`/`. Remote commands
are always submitted to the server prepended with an exclamation point: `!`.
#### Local Commands
The following list is a list of client commands which may be available to you through your Archipelago client. You
execute these commands in your client window.
The following commands are available in these clients: SNIClient, FactorioClient, FF1Client.
- `/connect <address:port>` Connect to the multiworld server.
- `/disconnect` Disconnects you from your current session.
- `/received` Displays all the items you have found or been sent.
- `/missing` Displays all the locations along with their current status (checked/missing).
- `/items` Lists all the item names for the current game.
- `/locations` Lists all the location names for the current game.
- `/ready` Sends ready status to the server.
- `/help` Returns a list of available commands.
- `/license` Returns the software licensing information.
- Just typing anything will broadcast a message to all players
##### FF1Client Only
The following command is only available when using the FF1Client for the Final Fantasy Randomizer.
- `/nes` Shows the current status of the NES connection.
##### SNIClient Only
The following command is only available when using the SNIClient for SNES based games.
- `/snes` Attempts to connect to your SNES device via SNI.
- `/snes_close` Closes the current SNES connection.
- `/slow_mode` Toggles on or off slow mode, which limits the rate in which you receive items.
##### FactorioClient Only
The following command is only available when using the FactorioClient to play Factorio with Archipelago.
- `/factorio <command text>` Sends the command argument to the Factorio server as a command.
#### Remote Commands
Remote commands may be executed by any client which allows for sending text chat to the Archipelago server. If your
client does not allow for sending chat then you may connect to your game slot with the TextClient which comes with the
Archipelago installation. In order to execute the command you need to merely send a text message with the command,
including the exclamation point.
- `!help` Returns a listing of available remote commands.
- `!license` Returns the software licensing information.
- `!countdown <countdown in seconds>` Starts a countdown using the given seconds value. Useful for synchronizing starts.
Defaults to 10 seconds if no argument is provided.
- `!options` Returns the current server options, including password in plaintext.
- `!admin <command>` Executes a command as if you typed it into the server console. Remote administration must be
enabled.
- `!players` Returns info about the currently connected and non-connected players.
- `!status` Returns information about your team. (Currently all players as teams are unimplemented.)
- `!remaining` Lists the items remaining in your game, but not where they are or who they go to.
- `!missing` Lists the location checks you are missing from the server's perspective.
- `!checked` Lists all the location checks you've done from the server's perspective.
- `!alias <alias>` Sets your alias.
- `!getitem <item>` Cheats an item, if it is enabled in the server.
- `!hint_location <location>` Hints for a location specifically. Useful in games where item names may match location
names such as Factorio.
- `!hint <item name>` Tells you at which location in whose game your Item is. Note you need to have checked some
locations to earn a hint. You can check how many you have by just running `!hint`
- `!forfeit` If you didn't turn on auto-forfeit or if you allowed forfeiting prior to goal completion. Remember that "
forfeiting" actually means sending out your remaining items in your world.
- `!collect` Grants you all the remaining checks in your world. Can only be used after your goal is complete or when you
have forfeited.
#### Host only (on Archipelago.gg or in your server console)
- `/help` Returns a list of commands available in the console.
- `/license` Returns the software licensing information.
- `/countdown <seconds>` Starts a countdown which is sent to all players via text chat. Defaults to 10 seconds if no
argument is provided.
- `/options` Lists the server's current options, including password in plaintext.
- `/save` Saves the state of the current multiworld. Note that the server autosaves on a minute basis.
- `/players` List currently connected players.
- `/exit` Shutdown the server
- `/alias <player name> <alias name>` Assign a player an alias.
- `/collect <player name>` Send out any items remaining in the multiworld belonging to the given player.
- `/forfeit <player name>` Forfeits someone regardless of settings and game completion status
- `/allow_forfeit <player name>` Allows the given player to use the `!forfeit` command.
- `/forbid_forfeit <player name>` Bars the given player from using the `!forfeit` command.
- `/send <player name> <item name>` Grants the given player the specified item.
- `/send_multiple <amount> <player name> <item name>` Grants the given player the stated amount of the specified item.
- `/hint <player name> <item or location name>` Send out a hint for the given item or location for the specified player.
- `/option <option name> <option value>` Set a server option. For a list of options, use the `/options` command.

215
worlds/generic/docs/plando_en.md Normal file
View File

@@ -0,0 +1,215 @@
# Archipelago Plando Guide
## 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
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, Minecraft and LTTP both support connection plando, but only LTTP supports text and boss
plando.
### 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 the 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:
```yaml
requires:
version: current.version.number
plando: bosses, items, texts, connections
```
## Item Plando
Item plando allows a player to place an item in a specific location or specific locations, 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 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.
* `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
### 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.
### Examples
```yaml
plando_items:
# example block 1 - Timespinner
- item:
Empire Orb: 1
Radiant Orb: 1
location: Starter Chest 1
from_pool: true
world: true
percentage: 50
# example block 2 - 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
- Forest Temple Bow Chest
- Fire Temple Megaton Hammer Chest
- Water Temple Longshot Chest
- Shadow Temple Hover Boots Chest
- Spirit Temple Silver Gauntlets Chest
world: false
# example block 3 - Slay the Spire
- items:
Boss Relic: 3
locations:
- Boss Relic 1
- Boss Relic 2
- Boss Relic 3
# example block 4 - 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 5 - Secret of Evermore
- items:
Levitate: 1
Revealer: 1
Energize: 1
locations:
- Master Sword Pedestal
- Boss Relic 1
world: true
count: 2
# example block 6 - 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 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.
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
## Boss Plando
As this is currently only supported by A Link to the Past instead of explaining here please refer to the
[relevant guide](/tutorial/zelda3/plando/en)
## Text Plando
As this is currently only supported by A Link to the Past instead of explaining here please refer to the
[relevant guide](/tutorial/zelda3/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.
* The options for connections are `percentage`, `entrance`, `exit`, and `direction`. Each of these options support
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)
[Minecraft connections](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/minecraft/Regions.py#L62)
### Examples
```yaml
plando_connections:
# example block 1 - 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
# example block 2 - Minecraft
- entrance: Overworld Structure 1
exit: Nether Fortress
direction: both
- entrance: Overworld Structure 2
exit: Village
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
Minecraft connection plando to work structure shuffle must be enabled.

85
worlds/generic/docs/setup_en.md Normal file
View File

@@ -0,0 +1,85 @@
# Archipelago Setup Guide
This guide is intended to provide an overview of how to install, set up, and run the Archipelago multiworld software.
This guide should take about 5 minutes to read.
## Installing the Archipelago software
The most recent public release of Archipelago can be found on the GitHub Releases page. GitHub Releases
page: [Archipelago Releases Page](https://github.com/ArchipelagoMW/Archipelago/releases).
Run the exe file, and after accepting the license agreement you will be prompted on which components you would like to
install.
The generator allows you to generate multiworld games on your computer. The ROM setups are required if anyone in the
game that you generate wants to play any of those games as they are needed to generate the relevant patch files.
The server will allow you to host the multiworld on your machine. Hosting on your machine requires forwarding the port
you are hosting on. The default port for Archipelago is `38281`. If you are unsure how to do this there are plenty of
other guides on the internet that will be more suited to your hardware.
The `Clients` are what are used to connect your game to the multiworld. If the game/games you plan to play are available
here go ahead and install these as well. If the game you choose to play is supported by Archipelago but not listed in
the installation check the setup guide for that game. Installing a client for a ROM based game requires you to have a
legally obtained ROM for that game as well.
## Generating a game
### What is a YAML?
YAML is the file format which Archipelago uses in order to configure a player's world. It allows you to dictate which
game you will be playing as well as the settings you would like for that game.
YAML is a format very similar to JSON however it is made to be more human-readable. If you are ever unsure of the
validity of your YAML file you may check the file by uploading it to the check page on the Archipelago website. Check
page: [YAML Validation Page](/mysterycheck)
### Creating a YAML
YAML files may be generated on the Archipelago website by visiting the games page and clicking the "Settings Page" link
under any game. Clicking "Export Settings" in a game's settings page will download the YAML to your system. Games
page: [Archipelago Games List](/games)
In a multiworld there must be one YAML per world. Any number of players can play on each world using either the game's
native coop system or using Archipelago's coop support. Each world will hold one slot in the multiworld and will have a
slot name and, if the relevant game requires it, files to associate it with that multiworld.
If multiple people plan to play in one world cooperatively then they will only need one YAML for their coop world. If
each player is planning on playing their own game then they will each need a YAML.
### Gather All Player YAMLs
All players that wish to play in the generated multiworld must have a YAML file which contains the settings that they
wish to play with.
Typically, a single participant of the multiworld will gather the YAML files from all other players. After getting the
YAML files of each participant for your multiworld game they can be compressed into a ZIP folder to then be uploaded to
the multiworld generator page. Multiworld generator
page: [Archipelago Seed Generator Page](https://archipelago.gg/generate)
#### Rolling a YAML Locally
It is possible to roll the multiworld locally, using a local Archipelago installation. This is done by entering the
installation directory of the Archipelago installation and placing each YAML file in the `Players` folder. If the folder
does not exist then it can be created manually.
After filling the `Players` folder the `ArchipelagoGenerate.exe` program should be run in order to generate a
multiworld. The output of this process is placed in the `output` folder.
#### Changing local host settings for generation
Sometimes there are various settings that you may want to change before rolling a seed such as enabling race mode,
auto-forfeit, plando support, or setting a password.
All of these settings plus other options are able to be changed by modifying the `host.yaml` file in the Archipelago
installation folder. The settings chosen here are baked into the `.archipelago` file that gets output with the other
files after generation so if rolling locally ensure this file is edited to your liking *before* rolling the seed.
## Hosting an Archipelago Server
The output of rolling a YAML will be a `.archipelago` file which can be subsequently uploaded to the Archipelago host
game page. Archipelago host game page: [Archipelago Seed Upload Page](https://archipelago.gg/uploads)
The `.archipelago` file may be run locally in order to host the multiworld on the local machine. This is done by
running `ArchipelagoServer.exe` and pointing the resulting file selection prompt to the `.archipelago` file that was
generated.

129
worlds/generic/docs/triggers_en.md Normal file
View File

@@ -0,0 +1,129 @@
# Archipelago Triggers Guide
This guide details the use of the Archipelago YAML trigger system. This guide is intended for a more advanced user with
more in-depth knowledge of Archipelago YAML options as well as experience editing YAML files. This guide should take
about 5 minutes to read.
## What are triggers?
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.
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/zelda3/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 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.
- 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
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.
- 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.
- 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
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:
```yaml
A Link to the Past:
start_inventory:
Rupees (300): 2
```
This format must be:
```yaml
root option:
option to change:
desired result
```
### Examples
The above examples all together will end up looking like this:
```yaml
triggers:
- option_category: A Link to the Past
option_name: shop_item_slots
option_result: 15
options:
A Link to the Past:
start_inventory:
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 example:
```yaml
triggers:
- option_category: Timespinner
option_name: SpecificKeycards
option_result: true
options:
Timespinner:
Inverted: true
```
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
either your main options or to trigger from another trigger. Currently, this is the only way to trigger on "setting 1
AND setting 2".
For example:
```yaml
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
```
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".

33
worlds/generic/docs/using_website_en.md Normal file
View File

@@ -0,0 +1,33 @@
# Using the Archipelago Website
This guide encompasses the use cases for rolling and hosting multiworld games on the Archipelago website. This guide
should only take a couple of minutes to read.
## Rolling the Seed On the Website
1. After gathering the YAML files together in one location, select all the files and compress them into a `.ZIP` file.
2. Next go to the "Generate Game" page. Generate game
page: [Archipelago Seed Generation Page](https://archipelago.gg/generate). Here, you can adjust some server settings
such as forfeit rules and the cost for a player to use a hint before generation.
3. After adjusting the host settings to your liking click on the Upload File button and using the explorer window that
opens, navigate to the location where you zipped the player files and upload this zip. The page will generate your
game and refresh multiple times to check on completion status.
4. After the generation completes you will be on a Seed Info page that provides the seed, the date/time of creation, a
link to the spoiler log, if available, and links to any rooms created from this seed.
5. To begin playing, click on "Create New Room", which will take you to the room page. From here you can navigate back
to the Seed Info page or to the Tracker page. Sharing the link to the room page with your friends will provide them
with the necessary info and files for them to connect to the multiworld.
## Hosting a Pre-Generated Multiworld on the Website
The easiest and most recommended method is to generate the game on the website which will allow you to create a private
room with all the necessary files you can share, as well as hosting the game and supporting item trackers for various
games.
If for some reason the seed was rolled on a machine, then either the resulting zip file or the
resulting `AP_XXXXX.archipelago` inside the zip file can be uploaded to the host game page. Host game
page: [Archipelago Seed Upload Page](https://archipelago.gg/uploads)
This will give a page with the seed info and a link to the spoiler log, if it exists. Click on "Create New Room" and
then share the link to the resulting page the other players so that they can download their patches or mods. The room
will also have a link to a Multiworld Tracker and tell you what the players need to connect to from their clients.