diff --git a/WebHostLib/static/assets/tutorial/archipelago/advanced_settings_en.md b/WebHostLib/static/assets/tutorial/archipelago/advanced_settings_en.md new file mode 100644 index 00000000..6b02d6fd --- /dev/null +++ b/WebHostLib/static/assets/tutorial/archipelago/advanced_settings_en.md @@ -0,0 +1,92 @@ +# Advanced Game Options Guide + + +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. + +## YAML Formatting? +YAML files are a format of human-readable 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. + +Typical YAML format will look as follows: +```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. + * `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). + +### 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. + +#### 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`, +and `exclude_locations`. +* `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. + diff --git a/WebHostLib/static/assets/tutorial/archipelago/setup_en.md b/WebHostLib/static/assets/tutorial/archipelago/setup_en.md index 4ce96731..ec8cc273 100644 --- a/WebHostLib/static/assets/tutorial/archipelago/setup_en.md +++ b/WebHostLib/static/assets/tutorial/archipelago/setup_en.md @@ -12,6 +12,17 @@ game/games you plan to play are available here go ahead and install these as wel supported by Archipelago but not listed in the installation check the relevant tutorial. ## 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. + ### 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. @@ -51,6 +62,7 @@ The generator will put a zip folder into your `Archipelago\output` folder with t 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. diff --git a/WebHostLib/static/assets/tutorial/tutorials.json b/WebHostLib/static/assets/tutorial/tutorials.json index 50e1964f..2762aa7a 100644 --- a/WebHostLib/static/assets/tutorial/tutorials.json +++ b/WebHostLib/static/assets/tutorial/tutorials.json @@ -4,7 +4,7 @@ "tutorials": [ { "name": "Multiworld Setup Tutorial", - "description": "A Guide to setting up the Archipelago software to generate multiworld games on your computer.", + "description": "A guide to setting up the Archipelago software to generate and host multiworld games on your computer and using the website.", "files": [ { "language": "English", @@ -16,9 +16,23 @@ } ] }, + { + "name": "Using Advanced Settings", + "description": "A guide to reading yaml files and editing them to fully customize your game.", + "files": [ + { + "language": "English", + "filename": "archipelago/advanced_settings_en.md", + "link": "archipelago/advanced_settings/en", + "authors": [ + "alwaysintreble" + ] + } + ] + }, { "name": "Archipelago Triggers Guide", - "description": "A Guide to setting up and using triggers in your game settings.", + "description": "A guide to setting up and using triggers in your game settings.", "files": [ { "language": "English",