Core: Reword item classification definitions to allow for progression + useful (#3925)

* Core: Reword item classification definitions to allow for progression + useful

* Update network protocol.md

* Update world api.md

* Update Fill.py

* Docstrings

* Update BaseClasses.py

* Update advanced_settings_en.md

* Update advanced_settings_en.md

* Update advanced_settings_en.md

* space

BaseClasses.py

@@ -1254,13 +1254,26 @@ class Location:
 
 
 class ItemClassification(IntFlag):
-    filler = 0b0000  # aka trash, as in filler items like ammo, currency etc,
+    filler = 0b0000
-    progression = 0b0001  # Item that is logically relevant
+    """ aka trash, as in filler items like ammo, currency etc """
-    useful = 0b0010  # Item that is generally quite useful, but not required for anything logical
+
-    trap = 0b0100  # detrimental item
+    progression = 0b0001
-    skip_balancing = 0b1000  # should technically never occur on its own
+    """ Item that is logically relevant.
-    # Item that is logically relevant, but progression balancing should not touch.
+    Protects this item from being placed on excluded or unreachable locations. """
-    # Typically currency or other counted items.
+
+    useful = 0b0010
+    """ Item that is especially useful.
+    Protects this item from being placed on excluded or unreachable locations.
+    When combined with another flag like "progression", it means "an especially useful progression item". """
+
+    trap = 0b0100
+    """ Item that is detrimental in some way. """
+
+    skip_balancing = 0b1000
+    """ should technically never occur on its own
+    Item that is logically relevant, but progression balancing should not touch.
+    Typically currency or other counted items. """
+
     progression_skip_balancing = 0b1001  # only progression gets balanced
 
     def as_flag(self) -> int:

Fill.py

@@ -537,7 +537,7 @@ def distribute_items_restrictive(multiworld: MultiWorld,
     if excludedlocations:
         raise FillError(
             f"Not enough filler items for excluded locations. "
-            f"There are {len(excludedlocations)} more excluded locations than filler or trap items.",
+            f"There are {len(excludedlocations)} more excluded locations than excludable items.",
             multiworld=multiworld,
         )
 

docs/network protocol.md

@@ -540,7 +540,7 @@ In JSON this may look like:
 | ----- | ----- |
 | 0 | Nothing special about this item |
 | 0b001 | If set, indicates the item can unlock logical advancement |
-| 0b010 | If set, indicates the item is important but not in a way that unlocks advancement |
+| 0b010 | If set, indicates the item is especially useful |
 | 0b100 | If set, indicates the item is a trap |
 
 ### JSONMessagePart

docs/world api.md

@@ -248,7 +248,8 @@ will all have the same ID. Name must not be numeric (must contain at least 1 let
 Other classifications include:
 
 * `filler`: a regular item or trash item
-* `useful`: generally quite useful, but not required for anything logical. Cannot be placed on excluded locations
+* `useful`: item that is especially useful. Cannot be placed on excluded or unreachable locations. When combined with
+another flag like "progression", it means "an especially useful progression item".
 * `trap`: negative impact on the player
 * `skip_balancing`: denotes that an item should not be moved to an earlier sphere for the purpose of balancing (to be
   combined with `progression`; see below)

worlds/generic/docs/advanced_settings_en.md

@@ -131,8 +131,8 @@ guide: [Archipelago Plando Guide](/tutorial/Archipelago/plando/en)
   the location without using any hint points.
 * `start_location_hints` is the same as `start_hints` but for locations, allowing you to hint for the item contained
   there without using any hint points.
-* `exclude_locations` lets you define any locations that you don't want to do and forces a filler or trap item which
+* `exclude_locations` lets you define any locations that you don't want to do and prevents items classified as
-  isn't necessary for progression into these locations.
+  "progression" or "useful" from being placed on them.
 * `priority_locations` lets you define any locations that you want to do and forces a progression item into these
   locations.
 * `item_links` allows players to link their items into a group with the same item link name and game. The items declared