From f3ca0a21c95cac1a4ae532f9511d7250dbca207b Mon Sep 17 00:00:00 2001 From: alwaysintreble Date: Fri, 10 Mar 2023 18:14:44 -0600 Subject: [PATCH] Docs: Add an option api doc (#1181) * write up an option api doc * address reviews * some clarification * add note about using schema * Add ItemSet and formatting * bulletpoint option defining Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> * split random description to new sentence Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> * use inclusive and parallel language for example Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> * changes from review * commas Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> * capitalize Toggle Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> * the sliver conventions --------- Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com> --- docs/options api.md | 188 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/options api.md diff --git a/docs/options api.md b/docs/options api.md new file mode 100644 index 00000000..a1407f2c --- /dev/null +++ b/docs/options api.md @@ -0,0 +1,188 @@ +# Archipelago Options API + +This document covers some of the generic options available using Archipelago's options handling system. + +For more information on where these options go in your world please refer to: + - [world api.md](/docs/world%20api.md) + +Archipelago will be abbreviated as "AP" from now on. + +## Option Definitions +Option parsing in AP is done using different Option classes. For each option you would like to have in your game, you +need to create: +- A new option class with a docstring detailing what the option will do to your user. +- A `display_name` to be displayed on the webhost. +- A new entry in the `option_definitions` dict for your World. +By style and convention, the internal names should be snake_case. If the option supports having multiple sub_options +such as Choice options, these can be defined with `option_my_sub_option`, where the preceding `option_` is required and +stripped for users, so will show as `my_sub_option` in yaml files and if `auto_display_name` is True `My Sub Option` +on the webhost. All options support `random` as a generic option. `random` chooses from any of the available +values for that option, and is reserved by AP. You can set this as your default value but you cannot define your own +new `option_random`. + +### Option Creation +As an example, suppose we want an option that lets the user start their game with a sword in their inventory. Let's +create our option class (with a docstring), give it a `display_name`, and add it to a dictionary that keeps track of our +options: + +```python +# Options.py +class StartingSword(Toggle): + """Adds a sword to your starting inventory.""" + display_name = "Start With Sword" + + +example_options = { + "starting_sword": StartingSword +} +``` + +This will create a `Toggle` option, internally called `starting_sword`. To then submit this to the multiworld, we add it +to our world's `__init__.py`: + +```python +from worlds.AutoWorld import World +from .Options import options + + +class ExampleWorld(World): + option_definitions = options +``` + +### Option Checking +Options are parsed by `Generate.py` before the worlds are created, and then the option classes are created shortly after +world instantiation. These are created as attributes on the MultiWorld and can be accessed with +`self.multiworld.my_option_name[self.player]`. This is the option class, which supports direct comparison methods to +relevant objects (like comparing a Toggle class to a `bool`). If you need to access the option result directly, this is +the option class's `value` attribute. For our example above we can do a simple check: +```python +if self.multiworld.starting_sword[self.player]: + do_some_things() +``` + +or if I need a boolean object, such as in my slot_data I can access it as: +```python +start_with_sword = bool(self.multiworld.starting_sword[self.player].value) +``` + +## Generic Option Classes +These options are generically available to every game automatically, but can be overridden for slightly different +behavior, if desired. See `worlds/soe/Options.py` for an example. + +### Accessibility +Sets rules for availability of locations for the player. `Items` is for all items available but not necessarily all +locations, such as self-locking keys, but needs to be set by the world for this to be different from locations access. + +### ProgressionBalancing +Algorithm for moving progression items into earlier spheres to make the gameplay experience a bit smoother. Can be +overridden if you want a different default value. + +### LocalItems +Forces the players' items local to their world. + +### NonLocalItems +Forces the players' items outside their world. + +### StartInventory +Allows the player to define a dictionary of starting items with item name and quantity. + +### StartHints +Gives the player starting hints for where the items defined here are. + +### StartLocationHints +Gives the player starting hints for the items on locations defined here. + +### ExcludeLocations +Marks locations given here as `LocationProgressType.Excluded` so that progression items can't be placed on them. + +### PriorityLocations +Marks locations given here as `LocationProgressType.Priority` forcing progression items on them. + +### ItemLinks +Allows users to share their item pool with other players. Currently item links are per game. A link of one game between +two players will combine their items in the link into a single item, which then gets replaced with `World.create_filler()`. + +## Basic Option Classes +### Toggle +The example above. This simply has 0 and 1 as its available results with 0 (false) being the default value. Cannot be +compared to strings but can be directly compared to True and False. + +### DefaultOnToggle +Like Toggle, but 1 (true) is the default value. + +### Choice +A numeric option allowing you to define different sub options. Values are stored as integers, but you can also do +comparison methods with the class and strings, so if you have an `option_early_sword`, this can be compared with: +```python +if self.multiworld.sword_availability[self.player] == "early_sword": + do_early_sword_things() +``` + +or: +```python +from .Options import SwordAvailability + +if self.multiworld.sword_availability[self.player] == SwordAvailability.option_early_sword: + do_early_sword_things() +``` + +### Range +A numeric option allowing a variety of integers including the endpoints. Has a default `range_start` of 0 and default +`range_end` of 1. Allows for negative values as well. This will always be an integer and has no methods for string +comparisons. + +### SpecialRange +Like range but also allows you to define a dictionary of special names the user can use to equate to a specific value. +For example: +```python +special_range_names: { + "normal": 20, + "extreme": 99, +} +``` + +will let users use the names "normal" or "extreme" in their options selections, but will still return those as integers +to you. Useful if you want special handling regarding those specified values. + +## More Advanced Options +### FreeText +This is an option that allows the user to enter any possible string value. Can only be compared with strings, and has +no validation step, so if this needs to be validated, you can either add a validation step to the option class or +within the world. + +### TextChoice +Like choice allows you to predetermine options and has all of the same comparison methods and handling. Also accepts any +user defined string as a valid option, so will either need to be validated by adding a validation step to the option +class or within world, if necessary. Value for this class is `Union[str, int]` so if you need the value at a specified +point, `self.multiworld.my_option[self.player].current_key` will always return a string. + +### PlandoBosses +An option specifically built for handling boss rando, if your game can use it. Is a subclass of TextChoice so supports +everything it does, as well as having multiple validation steps to automatically support boss plando from users. If +using this class, you must define `bosses`, a set of valid boss names, and `locations`, a set of valid boss location +names, and `def can_place_boss`, which passes a boss and location, allowing you to check if that placement is valid for +your game. When this function is called, `bosses`, `locations`, and the passed strings will all be lowercase. There is +also a `duplicate_bosses` attribute allowing you to define if a boss can be placed multiple times in your world. False +by default, and will reject duplicate boss names from the user. For an example of using this class, refer to +`worlds.alttp.options.py` + +### OptionDict +This option returns a dictionary. Setting a default here is recommended as it will output the dictionary to the +template. If you set a [Schema](https://pypi.org/project/schema/) on the class with `schema = Schema()`, then the +options system will automatically validate the user supplied data against the schema to ensure it's in the correct +format. + +### ItemDict +Like OptionDict, except this will verify that every key in the dictionary is a valid name for an item for your world. + +### OptionList +This option defines a List, where the user can add any number of strings to said list, allowing duplicate values. You +can define a set of keys in `valid_keys`, and a default list if you want certain options to be available without editing +for this. If `valid_keys_casefold` is true, the verification will be case-insensitive; `verify_item_name` will check +that each value is a valid item name; and`verify_location_name` will check that each value is a valid location name. + +### OptionSet +Like OptionList, but returns a set, preventing duplicates. + +### ItemSet +Like OptionSet, but will verify that all the items in the set are a valid name for an item for your world.