diff --git a/BaseClasses.py b/BaseClasses.py index 98ada4f8..e5c187b9 100644 --- a/BaseClasses.py +++ b/BaseClasses.py @@ -1254,13 +1254,26 @@ class Location: class ItemClassification(IntFlag): - filler = 0b0000 # aka trash, as in filler items like ammo, currency etc, - progression = 0b0001 # Item that is logically relevant - useful = 0b0010 # Item that is generally quite useful, but not required for anything logical - trap = 0b0100 # detrimental item - 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. + filler = 0b0000 + """ aka trash, as in filler items like ammo, currency etc """ + + progression = 0b0001 + """ Item that is logically relevant. + Protects this item from being placed on excluded or unreachable locations. """ + + 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: diff --git a/Fill.py b/Fill.py index 86a4639c..45c4def9 100644 --- a/Fill.py +++ b/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, ) diff --git a/docs/network protocol.md b/docs/network protocol.md index 2ad8d4c4..160f8303 100644 --- a/docs/network protocol.md +++ b/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 diff --git a/docs/world api.md b/docs/world api.md index 445e68e7..487c5b4a 100644 --- a/docs/world api.md +++ b/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) diff --git a/worlds/generic/docs/advanced_settings_en.md b/worlds/generic/docs/advanced_settings_en.md index 2197c070..e78eb915 100644 --- a/worlds/generic/docs/advanced_settings_en.md +++ b/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 - isn't necessary for progression into these locations. +* `exclude_locations` lets you define any locations that you don't want to do and prevents items classified as + "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