Templates: Update template output and add min and max comments for named special_range options. (#1164)

* add min and max comments for named special_range options

* comment all special range options and dictate the min and max in comment block

* make it cleaner

* make it cleanerer

* make it cleanererer

* Reformat template for more consistent comments.

* Fixed missing note on some special settings.

* Small tweak to template.

* Update playerSettings.yaml to match auto-generated template with all ALTTP options.

* Fix edge case with `special_range_cutoff` and revert playerSettings.yaml.

Co-authored-by: Zach Parks <zach@alliware.com>

Options.py

@@ -850,7 +850,7 @@ class Accessibility(Choice):
 
 class ProgressionBalancing(SpecialRange):
     """A system that can move progression earlier, to try and prevent the player from getting stuck and bored early.
-    [0-99, default 50] A lower setting means more getting stuck. A higher setting means less getting stuck."""
+    A lower setting means more getting stuck. A higher setting means less getting stuck."""
     default = 50
     range_start = 0
     range_end = 99

WebHostLib/options.py

@@ -25,26 +25,14 @@ def create():
             os.unlink(full_path)
 
     def dictify_range(option: typing.Union[Options.Range, Options.SpecialRange]):
-        data = {}
-        special = getattr(option, "special_range_cutoff", None)
-        if special is not None:
-            data[special] = 0
-        data.update({
-            option.range_start: 0,
-            option.range_end: 0,
-            option.default: 50
-        })
-        for sub_option in {"random", "random-low", "random-high"}:
+        data = {option.default: 50}
+        for sub_option in ["random", "random-low", "random-high"]:
             if sub_option != option.default:
                 data[sub_option] = 0
 
-        notes = {
-            special: "minimum value without special meaning",
-            option.range_start: "minimum value",
-            option.range_end: "maximum value"
-        }
-
+        notes = {}
         for name, number in getattr(option, "special_range_names", {}).items():
+            notes[name] = f"equivalent to {number}"
             if number in data:
                 data[name] = data[number]
                 del data[number]

WebHostLib/templates/options.yaml

@@ -1,60 +1,86 @@
-# What is this file?
-# This file contains options which allow you to configure your multiworld experience while allowing others
-# to play how they want as well.
-
-# How do I use it?
-# The options in this file are weighted. This means the higher number you assign to a value, the more
-# chances you have for that option to be chosen. For example, an option like this:
+# Q. What is this file?
+# A. This file contains options which allow you to configure your multiworld experience while allowing
+#    others to play how they want as well.
 #
-# map_shuffle:
-#   on: 5
-#   off: 15
+# Q. How do I use it?
+# A. The options in this file are weighted. This means the higher number you assign to a value, the
+#    more chances you have for that option to be chosen. For example, an option like this:
 #
-# Means you have 5 chances for map shuffle to occur, and 15 chances for map shuffle to be turned off
+#    map_shuffle:
+#      on: 5
+#      off: 15
+#
+#    Means you have 5 chances for map shuffle to occur, and 15 chances for map shuffle to be turned
+#    off.
+#
+# Q. I've never seen a file like this before. What characters am I allowed to use?
+# A. This is a .yaml file. You are allowed to use most characters.
+#    To test if your yaml is valid or not, you can use this website:
+#        http://www.yamllint.com/
+#    You can also verify your Archipelago settings are valid at this site:
+#        https://archipelago.gg/check
 
-# I've never seen a file like this before. What characters am I allowed to use?
-# This is a .yaml file. You are allowed to use most characters.
-# To test if your yaml is valid or not, you can use this website:
-# http://www.yamllint.com/
+# Your name in-game. Spaces will be replaced with underscores and there is a 16-character limit.
+#   {player} will be replaced with the player's slot number.
+#   {PLAYER} will be replaced with the player's slot number, if that slot number is greater than 1.
+#   {number} will be replaced with the counter value of the name.
+#   {NUMBER} will be replaced with the counter value of the name, if the counter value is greater than 1.
+name: Player{number}
 
-description: Default {{ game }} Template # Used to describe your yaml. Useful if you have multiple files
-# Your name in-game. Spaces will be replaced with underscores and there is a 16 character limit
-name: YourName{number}
-#{player} will be replaced with the player's slot number.
-#{PLAYER} will be replaced with the player's slot number if that slot number is greater than 1.
-#{number} will be replaced with the counter value of the name.
-#{NUMBER} will be replaced with the counter value of the name if the counter value is greater than 1.
-game:
-  {{ game }}: 1
+# Used to describe your yaml. Useful if you have multiple files.
+description: Default {{ game }} Template
+
+game: {{ game }}
 requires:
   version: {{ __version__ }} # Version of Archipelago required for this yaml to work as expected.
-# Shared Options supported by all games:
 
 {%- macro range_option(option) %}
-    # you can add additional values between minimum and maximum
+    # You can define additional values between the minimum and maximum values.
+    # Minimum value is {{ option.range_start }}
+    # Maximum value is {{ option.range_end }}
     {%- set data, notes = dictify_range(option) %}
     {%- for entry, default in data.items() %}
     {{ entry }}: {{ default }}{% if notes[entry] %} # {{ notes[entry] }}{% endif %}
     {%- endfor -%}
 {% endmacro %}
+
 {{ game }}:
   {%- for option_key, option in options.items() %}
-  {{ option_key }}:{% if option.__doc__ %} # {{ option.__doc__ | replace('\n', '\n#') | indent(4, first=False) }}{% endif %}
+  {{ option_key }}:
+    {%- if option.__doc__ %}
+    # {{ option.__doc__
+      | trim
+      | wordwrap(112, wrapstring="\n# ")
+      | replace('    ', '')
+      | replace('\n    ', '\n# ')
+      | indent(4, first=False)
+    }}
+    {%- endif -%}
+
+    {%- if option.__doc__ and option.range_start is defined %}
+    #
+    {%- endif -%}
+
     {%- if option.range_start is defined and option.range_start is number %}
     {{- range_option(option) -}}
+
     {%- elif option.options -%}
-      {%- for suboption_option_id, sub_option_name in option.name_lookup.items() %}
+    {%- for suboption_option_id, sub_option_name in option.name_lookup.items() %}
     {{ sub_option_name }}: {% if suboption_option_id == option.default %}50{% else %}0{% endif %}
-      {%- endfor -%}
-      {% if option.name_lookup[option.default] not in option.options %}
+    {%- endfor -%}
+
+    {%- if option.name_lookup[option.default] not in option.options %}
     {{ option.default }}: 50
-      {%- endif -%}
+    {%- endif -%}
+
     {%- elif option.default is string %}
     {{ option.default }}: 50
+
     {%- elif option.default is iterable and option.default is not mapping %}
     {{ option.default | list }}
+
     {%- else %}
-    {{ yaml_dump(option.default) | indent(4, first=false) }}
+    {{ yaml_dump(option.default) | trim | indent(4, first=false) }}
     {%- endif -%}
   {%- endfor %}
-  {% if not options %}{}{% endif %}
+

playerSettings.yaml

@@ -453,7 +453,7 @@ A Link to the Past:
   death_link:
     false: 50
     true: 0
-    
+
   allow_collect: # Allows for !collect / co-op to auto-open chests containing items for other players.
     #    Off by default, because it currently crashes on real hardware.
     false: 50