Docs: Make an actual LogicMixin spec & explanation

docs/world api.md

@@ -696,9 +696,73 @@ When importing a file that defines a class that inherits from `worlds.AutoWorld.
 is automatically extended by the mixin's members. These members should be prefixed with the name of the implementing
 world since the namespace is shared with all other logic mixins.
 
-Some uses could be to add additional variables to the state object, or to have a custom state machine that gets modified
-with the state.
-Please do this with caution and only when necessary.
+In general, a LogicMixin class should have at least one mutable variable that is tracking some custom state per player,
+as well as an `init_mixin` and a `copy_mixin` function so that this variable gets initialized and copied correctly when
+`CollectionState()` and `CollectionState.copy()` are called respectively.
+
+```python
+from BaseClasses import CollectionState, MultiWorld
+from worlds.AutoWorld import LogicMixin
+
+class MyGameState(LogicMixin):
+    defeatable_enemies: Dict[int, Set[str]]  # per player
+
+    def init_mixin(self, multiworld: MultiWorld) -> None:
+        self.defeatable_enemies = {}
+
+    def copy_mixin(self, new_state: CollectionState) -> CollectionState:
+        # Be careful to make a "deep enough" copy here!
+        new_state.defeatable_enemies = {player: enemies.copy() for player, enemies in self.defeatable_enemies.items()}
+```
+
+After doing this, you can now access `state.defeatable_enemies[player]` from your access rules.
+
+Usually, doing this coincides with an override of `World.collect` and `World.remove`, where any time a relevant item is
+collected or removed, the custom state variable gets recalculated.
+
+```python
+# __init__.py
+
+def collect(self, state: CollectionState, item: Item) -> bool:
+    change = super().collect(state, item)
+    if change and item in COMBAT_ITEMS:
+        state.defeatable_enemies |= get_newly_unlocked_enemies(state)
+    return change
+
+def remove(self, state: CollectionState, item: Item) -> bool:
+    change = super().remove(state, item)
+    if change and item in COMBAT_ITEMS:
+        state.defeatable_enemies -= get_newly_locked_enemies(state)
+    return change
+```
+
+Using LogicMixin can slow down your code by a lot if you don't use it intelligently.  
+For example, you can make use of the fact that `collect` should only unlock things, and `remove` should only
+lock things.
+In our example, we have two different functions: `get_newly_unlocked_enemies` and `get_newly_locked_enemies`.  
+`get_newly_unlocked_enemies` should only consider enemies that are *not already in the set*
+and check whether they were **unlocked**.  
+`get_newly_locked_enemies` should only consider enemies that are *already in the set*
+and check whether they **became locked**.
+
+There are a multitude of other ways you can optimise LogicMixin. Some games use a `mygame_state_is_stale`
+variable that they simply set to True in `collect`, `remove`, and `init_mixin`.  
+The calls to the actual recalculating functions are then moved to the start of the relevant access rules like this:
+
+```python
+def can_defeat_enemy(state: CollectionState, player: int, enemy: str) -> bool:
+    if state.custom_state_is_stale[player]:
+        state.defeatable_enemies = recalculate_defeatable_enemies(state)
+        state.custom_state_is_stale[player] = False
+
+    return enemy in state.defeatable_enemies
+```
+
+This can help quite significantly because it is possible for 0 local access rules to be called between two calls to
+`collect`, so recalculating on every `collect` is very slow.
+
+Only use LogicMixin if necessary. There are often other ways to achieve what it does, like making clever use of
+`state.prog_items`, or using event items, pseudo-regions etc.
 
 #### pre_fill