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

WebHost: Edit Archipelago category guides and enabled two-spaced nested lists.

This commit is contained in:
Hussein Farran 2021-11-29 22:26:08 -05:00
parent c083716627
commit 5121b0d09b
5 changed files with 163 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
WebHostLib/static/assets/tutorial.js
View File

@ -23,6 +23,7 @@ window.addEventListener('load', () => {
showdown.setOption('tables', true);
showdown.setOption('strikethrough', true);
showdown.setOption('literalMidWordUnderscores', true);
showdown.setOption('disableForced4SpacesIndentedSublists', true);
tutorialWrapper.innerHTML += (new showdown.Converter()).makeHtml(results);
adjustHeaderWidth();

162
WebHostLib/static/assets/tutorial/archipelago/advanced_settings_en.md
View File

@ -1,23 +1,23 @@
# Advanced Game Options Guide
# 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 Archipelago system generates games using player configuration files as input. Generally these are going to be
YAML files and each player will have one of these containing their custom settings for the randomized game they want to play.
On the website when you customize your settings from one of the game player settings pages which you can reach from the
[supported games page](/games). Clicking on the export settings button at the bottom will provide you with a pre-filled out
YAML with your options. The player settings page also has an option to download a fully filled out yaml containing every
option with every available setting for the available options.
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: https://archipelago.gg/games
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 an option to download a fully filled out yaml containing every option with every available setting for the available options.
## 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 <span data-tooltip="Allegedly.">human-readable</span> markup config files. The basic syntax
of a yaml file will have `root` and then different levels of `nested` text that the generator "reads" in order to determine
your settings. To nest text, the correct syntax is **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](https://www.sublimetext.com/).
This program out of the box supports the correct formatting for the YAML file, so you will be able to tab and get proper
highlighting for any potential errors made while editing the file. If using any other text editor such as Notepad or
Notepad++ whenever you move to nest an option that it is done with two spaces and not tabs.
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.
Typical YAML format will look as follows:
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: 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:
@ -28,69 +28,60 @@ root_option:
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.
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.
* `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
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 turned `on` or `off` and is `on` by default.
* `triggers` is one of the more advanced options that allows you to create conditional adjustments. You can read more
about this [here](/tutorial/archipelago/triggers/en).
* `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 turned `on` or `off` and is `on` by default.
* `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: https://archipelago.gg/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 in the format
`GameName`. 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.
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](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.
### Example
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: https://archipelago.gg/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 the item `Rupees(5)` six times, totalling 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.
### Example YAML
```yaml
@ -133,28 +124,33 @@ triggers:
#### 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 meaning we will likely receive important items earlier increasing the chance of having
things to do.
* `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 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.
* `start_inventory` defines an area for us to determine what items we would like to start the seed with. For this example
we have:
* `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.
* `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.
* `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.
* `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.
* `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.
* `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.

105
WebHostLib/static/assets/tutorial/archipelago/setup_en.md
View File

@ -1,79 +1,58 @@
# 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 [here](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 optional but are required if
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 but this also requires you to port forward. The
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 you use to connect your game to the multiworld. If the
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 relevant tutorial.
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
### Creating a YAML
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, but if each player is planning on
playing their own game then they will each need a YAML. These YAML files can be generated by going to the relevant game's
player settings page, entering the name they want to use for the game, setting the options to what they would like to
play with and then clicking on the export settings button. This will then download a YAML file that will contain all of
these options and this can then be given to whoever is going to generate the 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.
### Gather all player YAMLS
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: https://archipelago.gg/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: https://archipelago.gg/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.
A YAML is a file which contains human readable markup. In other words, this is a settings file kind of like an INI file or a TOML file.
Each player can go to the game's player settings page in order to determine the settings how they want them and then download a YAML file containing these settings.
After getting the YAML files of each participant for your multiworld game, these can all either be placed together in the
`Archipelago\Players` folder or compressed into a ZIP folder to then be uploaded to the [website generator](/generate).
If rolling locally ensure that the folder is clear of any files you do not wish to include in the game such as the
included default player settings files.
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: 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. The output wll be a `.archipelago` file which can be subsequently uploaded to the Archipelago host game page. Archipelago host game page: https://archipelago.gg/uploads
The `.AP` 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.
#### 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 base `Archipelago` folder. The settings chosen here are baked into
the serverdata file that gets output with the other files after generation so if rolling locally ensure this file is edited
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.
### Rolling the seed
#### On the Website
After gathering the YAML files together in one location, select all of the files and compress them into a .zip folder.
Next go to the [Start Playing](/start-playing) page and click on `generate a randomized game` to reach the website generator.
Here, you can adjust some server settings such as forfeit rules and the cost for a player to use a hint before generation.
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. 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.
To begin playing, click on `Create New Room`, which will take you to the room page. From here you can navigate back to thse
Seed Info page or to the Tracker page. Sharing the link to this page with your friends will provide them with the
necessary info and files for them to connect to the multiworld.
#### Rolling using the generation program
After gathering the YAML files together in the `Archipelago\Players` folder, run the program `ArchipelagoGenerate.exe`
in the base `Archipelago` folder. This will then open a console window and either silently close itself or spit out an
error. If you receive an error, it is likely due to an error in the YAML file. If the error is unhelpful in figuring
out the issue asking in the ***#tech-support*** channel of our Discord for help with finding it is highly recommended.
The generator will put a zip folder into your `Archipelago\output` folder with the format `AP_XXXXXXXXX`.zip.
This contains the patch files and relevant mods for the players as well as the serverdata for the host.
## Hosting a multiworld
### Uploading the seed to 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 [upload page](/uploads). This will give a page with the seed info and have a
link to the spoiler if it exists. Click on Create New room and then share the link for the room with 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.
### Hosting a seed locally
For this we'll assume you have already port forwarding `38281` and have generated a seed that is still in the `outputs`
folder. Next, you'll want to run `ArchipelagoServer.exe`. A window will open in order to open the multiworld data for the
game. You can either use the generated zip folder or extract the .archipelago file and use it. If everything worked correctly the console window should tell you it's now hosting a game with the IP, port, and password that clients will need in order to connect.
Extract the patch and mod files then send those to your friends, and you're done!

26
WebHostLib/static/assets/tutorial/archipelago/using_website_en.md Normal file
View File

@ -0,0 +1,26 @@
# 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: 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: 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.

16
WebHostLib/static/assets/tutorial/tutorials.json
View File

@ -17,7 +17,21 @@
]
},
{
"name": "Using Advanced Settings",
"name": "Archipelago Website User Guide",
"description": "A guide to using the Archipelago website to generate multiworlds or host pre-generated multiworlds.",
"files": [
{
"language": "English",
"filename": "archipelago/using_website.md",
"link": "archipelago/using_website/en",
"authors": [
"alwaysintreble"
]
}
]
},
{
"name": "Advanced YAML Guide",
"description": "A guide to reading yaml files and editing them to fully customize your game.",
"files": [
{