From 38ce51d2ef7677091ecaa57a5e9b794ea57e4783 Mon Sep 17 00:00:00 2001 From: Ixrec Date: Sat, 24 Feb 2024 16:01:54 +0000 Subject: [PATCH] Docs: Clarify which kinds of options actually support "random" (#2845) * Clarify which kinds of options actually support "random" The current phrasing of this sentence made me expect "random" to work even on my OptionsDict option. After asking `#archipelago-dev` and checking the `Options.py` code, it's become clear that many option types don't (and can't) support "random". This is my best guess at a more correct wording. * add a sentence about from_text overrides based on black-silver's suggestion --- docs/options api.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/options api.md b/docs/options api.md index bfab0096bba..1141528991d 100644 --- a/docs/options api.md +++ b/docs/options api.md @@ -24,8 +24,11 @@ display as `Value1` on the webhost. (i.e. `alias_value_1 = option_value1`) which will allow users to use either `value_1` or `value1` in their yaml files, and both will resolve as `value1`. This should be used when changing options around, i.e. changing a Toggle to a Choice, and defining `alias_true = option_full`. -- 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 `option_random`. +- All options with a fixed set of possible values (i.e. those which inherit from `Toggle`, `(Text)Choice` or +`(Named/Special)Range`) 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 `option_random`. +However, you can override `from_text` and handle `text == "random"` to customize its behavior or +implement it for additional option types. As an example, suppose we want an option that lets the user start their game with a sword in their inventory, an option to let the player choose the difficulty, and an option to choose how much health the final boss has. Let's create our