Move Predefined functions into non-hook Rules.py, Add YamlEnabled/Disabled functions, Add documentation for Predefined functions

Author: silasary

docs/syntax/requires.md

@@ -12,45 +12,45 @@ Okay, so we know what requires are. Let's talk about the different ways you can
 
 ## Boolean Logic (AND/OR)
 
-**Boolean logic is the default way to write requires in Manual.** It's called "boolean logic" because you're writing your logic much like you'd describe it normally: with a series of AND/OR combos. 
+**Boolean logic is the default way to write requires in Manual.** It's called "boolean logic" because you're writing your logic much like you'd describe it normally: with a series of AND/OR combos.
 
 For example, from the example above about Link to the Past and Thieves Town in the Dark World, let's assume that the first chest location in the dungeon has no additional requirements. So, we'd describe our logic for that first chest location as being "Moon Pearl and (either (Hammer and Power Glove) or Titan's Mitt)", same as the region itself. In Manual's boolean logic syntax, that would be:
 
 ```json
-{ 
+{
     "name": "First chest in Thieves Town",
     "requires": "|Moon Pearl| and ((|Hammer| and |Power Glove|) or |Titan's Mitt|)"
 }
 ```
 
-**You use `|pipes|` around item names and `(parentheses)` around your layers of nesting, if needed.** 
+**You use `|pipes|` around item names and `(parentheses)` around your layers of nesting, if needed.**
 
-- Pipes tell Manual where to look for entire item names. 
-- Parentheses tell Manual exactly how you're grouping your logic, since there's a difference between "Hammer and Power Glove or Titan's Mitt" and "(Hammer and Power Glove) or Titan's Mitt". 
+- Pipes tell Manual where to look for entire item names.
+- Parentheses tell Manual exactly how you're grouping your logic, since there's a difference between "Hammer and Power Glove or Titan's Mitt" and "(Hammer and Power Glove) or Titan's Mitt".
   - The former essentially evaluates to "Hammer and either Power Glove or Titan's Mitt", while the latter is very explicit about what the logic should be and evaluates correctly.
   - There's no theoretical limit to how many parentheses you can use, but try to not get past the practical limit of how many sets of parentheses you can reliably keep track of.
 
 ### Additional Examples of Boolean Logic
 
 Boss 1 Requires Ladder and Gloves, OR Sword and Shield, OR Bow and Quiver and Arrow (separate items): a simple case of various successful item sets. It's a few sets of ANDs separated by ORs.
 ```json
-{ 
+{
     "name": "Boss 1",
     "requires": "(|Ladder| and |Gloves|) or (|Sword| and |Shield|) or (|Bow| and |Quiver| and |Arrow|)"
 }
 ```
 
 Boss 2 simply requires one heart, a way to strike it (Sword, Spear or Club) and a way to dodge it (Double Jump, Dash or Slide): we're looking at different sets, and picking one item from which. It's many ORs inside a big set of ANDs.
 ```json
-{ 
+{
     "name": "Boss 2",
     "requires": "|Heart| and (|Sword| or |Spear| or |Club|) and (|Double Jump| or |Dash| or |Slide|)"
 }
 ```
 
 Now, say the final boss is a big dragon with a glaring weakness to Blizzard. However, if you don't have blizzard, you will need a spear for its reach and a way to dodge it, which is one of the three mobility from before. This is an OR (the mobility), inside an AND (Spear and Mobility), inside an OR (Blizzard it or fight it legitimately). Layered logic is as such:
 ```json
-{ 
+{
     "name": "Final Boss",
     "requires": "|Blizzard| or (|Spear| and (|Double Jump| or |Dash| or |Slide|))",
     "victory": true
@@ -61,15 +61,15 @@ Now, say the final boss is a big dragon with a glaring weakness to Blizzard. How
 
 As demonstrated in the [Making Items: Count](making/items.md#count) docs, you can configure an item to have more than one copy of that item in the world's item pool. Sometimes, you want to use multiple copies of an item as a requirement for accessing a location or region, and Manual supports this as well.
 
-The way to do this is a short suffix added to the end of any required item name separated by a colon, like this: `|Coin:25|`. 
+The way to do this is a short suffix added to the end of any required item name separated by a colon, like this: `|Coin:25|`.
 
 - That will tell Manual that the location/region requires 25 of that Coin item.
 
 Now that we know how to require multiple of an item, we can revise our Boss 2 example from above to make the boss a little easier to handle in-logic:
 
 > Boss 2 simply requires **FIVE hearts**, a way to strike it (Sword, Spear or Club) and a way to dodge it (Double Jump, Dash or Slide): we're looking at different sets, and picking one item from which. It's many ORs inside a big set of ANDs.
 > ```json
->{ 
+>{
 >    "name": "Boss 2",
 >    "requires": "|Heart:5| and (|Sword| or |Spear| or |Club|) and (|Double Jump| or |Dash| or |Slide|)"
 >}
@@ -106,13 +106,55 @@ The way to do this is using curly braces around the function name that you want
 - Note the lack of pipes (`|`). Functions are processed entirely differently than items/categories used as requirements.
 - Doing this will tell Manual that the function will either return a requires string to be processed, or will return true/false based on whether this requirement was met.
 
-Requirement functions can have no function arguments, or have any number of function arguments separated by commas. 
+Requirement functions can have no function arguments, or have any number of function arguments separated by commas.
 
 - Example with no function arguments: https://github.com/ManualForArchipelago/Manual/blob/main/src/hooks/Rules.py#L8-L15.
 - Example with one argument, add str arguments to the end of the function for more: https://github.com/ManualForArchipelago/Manual/blob/main/src/hooks/Rules.py#L17-L24
 
-Additionally, those functions can themselves return a dynamically-created requires string, which would then be processed normally in the spot where the function call was. 
+Additionally, those functions can themselves return a dynamically-created requires string, which would then be processed normally in the spot where the function call was.
 
 - Example of a returned requires string: https://github.com/ManualForArchipelago/Manual/blob/main/src/hooks/Rules.py#L26-L29
 
-\* By default, the only two generic requirement functions that we provide are the OptOne and OptAll, which are both focused on allowing a required item or items to pass the requirement even if the item(s) have been disabled through defined category options. The rest of the functions in the Rules hook file are examples.
+\* By default, the only two generic requirement functions that we provide are the OptOne and OptAll, which are both focused on allowing a required item or items to pass the requirement even if the item(s) have been disabled through defined category options. The rest of the functions in the Rules hook file are examples.
+
+## Bundled functions
+
+Manual comes with some helpful functions built in:
+
+### `OptOne(ItemName)`
+
+Requires an item only if that item exists.  Useful if an item might have been disabled by a yaml option.
+
+### `OptAll(ItemName)`
+
+I'm not sure how to document this function, nico pls help
+
+### `YamlEnabled(option_name)` and `YamlDisabled(option_name)`
+
+These allow you to check yaml options within your logic.
+
+You might use this to allow glitches
+
+```json
+{
+    "name": "Item on Cliff",
+    "requires": "|Double Jump| or {YamlEnabled(allow_hard_glitches)}"
+}
+```
+
+Or make key items optional
+
+```json
+{
+    "name": "Hidden Item in Pokemon",
+    "requires": "|Itemfinder| or {YamlDisabled(require_itemfinder)}"
+}
+```
+
+You can even combine the two in complex ways
+
+```json
+{
+    "name": "This is probably a region",
+    "requires": "({YamlEnabled(easy_mode)} and |Gravity|) or ({YamlDisabled(easy_mode)} and |Jump| and |Blizzard| and |Water|)"
+}

src/Rules.py

@@ -1,9 +1,10 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 from worlds.generic.Rules import set_rule
 from .Regions import regionMap
 from .hooks import Rules
 from BaseClasses import MultiWorld, CollectionState
-from .Helpers import clamp, is_item_enabled
+from .Helpers import clamp, is_item_enabled, get_items_with_value, is_option_enabled
+from worlds.AutoWorld import World
 
 import re
 import math
@@ -84,7 +85,15 @@ def checkRequireStringForArea(state: CollectionState, area: dict):
             func_args = item[1].split(",")
             if func_args == ['']:
                 func_args.pop()
-            func = getattr(Rules, func_name)
+
+            func = globals().get(func_name)
+
+            if func is None:
+                func = getattr(Rules, func_name)
+
+            if not callable(func):
+                raise ValueError(f"Invalid function `{func_name}` in {area}.")
+
             result = func(world, multiworld, state, player, *func_args)
             if isinstance(result, bool):
                 requires_list = requires_list.replace("{" + func_name + "(" + item[1] + ")}", "1" if result else "0")
@@ -261,3 +270,112 @@ def allRegionsAccessible(state):
 
     # Victory requirement
     multiworld.completion_condition[player] = lambda state: state.has("__Victory__", player)
+
+def ItemValue(world: "ManualWorld", multiworld: MultiWorld, state: CollectionState, player: int, args: str):
+    """When passed a string with this format: 'valueName:int',
+    this function will check if the player has collect at least 'int' valueName worth of items\n
+    eg. {ItemValue(Coins:12)} will check if the player has collect at least 12 coins worth of items
+    """
+
+    args_list = args.split(":")
+    if not len(args_list) == 2 or not args_list[1].isnumeric():
+        raise Exception(f"ItemValue needs a number after : so it looks something like 'ItemValue({args_list[0]}:12)'")
+    args_list[0] = args_list[0].lower().strip()
+    args_list[1] = int(args_list[1].strip())
+
+    if not hasattr(world, 'item_values_cache'): #Cache made for optimization purposes
+        world.item_values_cache = {}
+
+    if not world.item_values_cache.get(player, {}):
+        world.item_values_cache[player] = {
+            'state': {},
+            'count': {},
+            }
+
+    if (args_list[0] not in world.item_values_cache[player].get('count', {}).keys()
+            or world.item_values_cache[player].get('state') != dict(state.prog_items[player])):
+        #Run First Time or if state changed since last check
+        existing_item_values = get_items_with_value(world, multiworld, args_list[0])
+        total_Count = 0
+        for name, value in existing_item_values.items():
+            count = state.count(name, player)
+            if count > 0:
+                total_Count += count * value
+        world.item_values_cache[player]['count'][args_list[0]] = total_Count
+        world.item_values_cache[player]['state'] = dict(state.prog_items[player]) #save the current gotten items to check later if its the same
+    return world.item_values_cache[player]['count'][args_list[0]] >= args_list[1]
+
+
+# Two useful functions to make require work if an item is disabled instead of making it inaccessible
+def OptOne(world: "ManualWorld", multiworld: MultiWorld, state: CollectionState, player: int, item: str, items_counts: Optional[dict] = None):
+    """Check if the passed item (with or without ||) is enabled, then this returns |item:count|
+    where count is clamped to the maximum number of said item in the itempool.\n
+    Eg. requires: "{OptOne(|DisabledItem|)} and |other items|" become "|DisabledItem:0| and |other items|" if the item is disabled.
+    """
+    if item == "":
+        return "" #Skip this function if item is left blank
+    if not items_counts:
+        items_counts = world.get_item_counts()
+
+    require_type = 'item'
+
+    if '@' in item[:2]:
+        require_type = 'category'
+
+    item = item.lstrip('|@$').rstrip('|')
+
+    item_parts = item.split(":")
+    item_name = item
+    item_count = '1'
+
+    if len(item_parts) > 1:
+        item_name = item_parts[0]
+        item_count = item_parts[1]
+
+    if require_type == 'category':
+        if item_count.isnumeric():
+            #Only loop if we can use the result to clamp
+            category_items = [item for item in world.item_name_to_item.values() if "category" in item and item_name in item["category"]]
+            category_items_counts = sum([items_counts.get(category_item["name"], 0) for category_item in category_items])
+            item_count = clamp(int(item_count), 0, category_items_counts)
+        return f"|@{item_name}:{item_count}|"
+    elif require_type == 'item':
+        if item_count.isnumeric():
+            item_current_count = items_counts.get(item_name, 0)
+            item_count = clamp(int(item_count), 0, item_current_count)
+        return f"|{item_name}:{item_count}|"
+
+# OptAll check the passed require string and loop every item to check if they're enabled,
+def OptAll(world: "ManualWorld", multiworld: MultiWorld, state: CollectionState, player: int, requires: str):
+    """Check the passed require string and loop every item to check if they're enabled,
+    then returns the require string with items counts adjusted using OptOne\n
+    eg. requires: "{OptAll(|DisabledItem| and |@CategoryWithModifedCount:10|)} and |other items|"
+    become "|DisabledItem:0| and |@CategoryWithModifedCount:2| and |other items|" """
+    requires_list = requires
+
+    items_counts = world.get_item_counts()
+
+    functions = {}
+    if requires_list == "":
+        return True
+    for item in re.findall(r'\{(\w+)\(([^)]*)\)\}', requires_list):
+        #so this function doesn't try to get item from other functions, in theory.
+        func_name = item[0]
+        functions[func_name] = item[1]
+        requires_list = requires_list.replace("{" + func_name + "(" + item[1] + ")}", "{" + func_name + "(temp)}")
+    # parse user written statement into list of each item
+    for item in re.findall(r'\|[^|]+\|', requires):
+        itemScanned = OptOne(world, multiworld, state, player, item, items_counts)
+        requires_list = requires_list.replace(item, itemScanned)
+
+    for function in functions:
+        requires_list = requires_list.replace("{" + function + "(temp)}", "{" + func_name + "(" + functions[func_name] + ")}")
+    return requires_list
+
+def YamlEnabled(world: "ManualWorld", multiworld: MultiWorld, state: CollectionState, player: int, param: str) -> bool:
+    """Is a yaml option enabled?"""
+    return is_option_enabled(multiworld, player, param)
+
+def YamlDisabled(world: "ManualWorld", multiworld: MultiWorld, state: CollectionState, player: int, param: str) -> bool:
+    """Is a yaml option disabled?"""
+    return not is_option_enabled(multiworld, player, param)

src/data/locations.json

@@ -123,7 +123,7 @@
     {
         "name": "Beat the Game - Deadpool",
         "category": ["Unlocked Teams", "Right Side"],
-        "requires": "|Deadpool|"
+        "requires": "|Deadpool| or {YamlEnabled(free_deadpool)}"
     },
     {
         "name": "Beat the Game - Wolverine",