Allow worlds to provide item and location descriptions (#2409)

These are displayed in the weighted options page as hoverable tooltips.

worlds/AutoWorld.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import hashlib
 import logging
 import pathlib
+import re
 import sys
 import time
 from dataclasses import make_dataclass
@@ -51,11 +52,17 @@ class AutoWorldRegister(type):
         dct["item_name_groups"] = {group_name: frozenset(group_set) for group_name, group_set
                                    in dct.get("item_name_groups", {}).items()}
         dct["item_name_groups"]["Everything"] = dct["item_names"]
+        dct["item_descriptions"] = {name: _normalize_description(description) for name, description
+                                    in dct.get("item_descriptions", {}).items()}
+        dct["item_descriptions"]["Everything"] = "All items in the entire game."
         dct["location_names"] = frozenset(dct["location_name_to_id"])
         dct["location_name_groups"] = {group_name: frozenset(group_set) for group_name, group_set
                                        in dct.get("location_name_groups", {}).items()}
         dct["location_name_groups"]["Everywhere"] = dct["location_names"]
         dct["all_item_and_group_names"] = frozenset(dct["item_names"] | set(dct.get("item_name_groups", {})))
+        dct["location_descriptions"] = {name: _normalize_description(description) for name, description
+                                    in dct.get("location_descriptions", {}).items()}
+        dct["location_descriptions"]["Everywhere"] = "All locations in the entire game."
 
         # move away from get_required_client_version function
         if "game" in dct:
@@ -205,9 +212,23 @@ class World(metaclass=AutoWorldRegister):
     item_name_groups: ClassVar[Dict[str, Set[str]]] = {}
     """maps item group names to sets of items. Example: {"Weapons": {"Sword", "Bow"}}"""
 
+    item_descriptions: ClassVar[Dict[str, str]] = {}
+    """An optional map from item names (or item group names) to brief descriptions for users.
+
+    Individual newlines and indentation will be collapsed into spaces before these descriptions are
+    displayed. This may cover only a subset of items.
+    """
+
     location_name_groups: ClassVar[Dict[str, Set[str]]] = {}
     """maps location group names to sets of locations. Example: {"Sewer": {"Sewer Key Drop 1", "Sewer Key Drop 2"}}"""
 
+    location_descriptions: ClassVar[Dict[str, str]] = {}
+    """An optional map from location names (or location group names) to brief descriptions for users.
+
+    Individual newlines and indentation will be collapsed into spaces before these descriptions are
+    displayed. This may cover only a subset of locations.
+    """
+
     data_version: ClassVar[int] = 0
     """
     Increment this every time something in your world's names/id mappings changes.
@@ -462,3 +483,17 @@ def data_package_checksum(data: "GamesPackage") -> str:
     assert sorted(data) == list(data), "Data not ordered"
     from NetUtils import encode
     return hashlib.sha1(encode(data).encode()).hexdigest()
+
+
+def _normalize_description(description):
+    """Normalizes a description in item_descriptions or location_descriptions.
+
+    This allows authors to write descritions with nice indentation and line lengths in their world
+    definitions without having it affect the rendered format.
+    """
+    # First, collapse the whitespace around newlines and the ends of the description.
+    description = re.sub(r' *\n *', '\n', description.strip())
+    # Next, condense individual newlines into spaces.
+    description = re.sub(r'(?<!\n)\n(?!\n)', ' ', description)
+    return description
+