Refactor code and enhance documentation in Cooperative Cuisine project

Several sections of the codebase have been refactored for maintainability. The 'ORDERS' module has witnessed some cleanups and adjustments in the 'create_init_orders' method. Hooks and associated comments were added in the 'hooks' module for better understanding of code functionality. The 'pygame_2d_vis' script's documentation was also improved for clarity.

cooperative_cuisine/hooks.py

@@ -299,53 +299,217 @@ Args:
 
 
 PRE_SERVING = "pre_serving"
+"""Called if player wants to drop off on `ServingWindow`.
+
+Args:
+    counter (ServingWindow): the serving window the player wants to serve on.
+    item (Item): the item to serve (on the player's hand).
+    env_time (datetime): current env time.
+    player (str): the player id.
+"""
 POST_SERVING = "post_serving"
+"""Serving was successful.
+
+Args:
+    counter (ServingWindow): the serving window on which the item was served on.
+    item (Item): the item that was served. (Plate)
+    env_time (datetime): current env time.
+    player (str): the player id.
+"""
 NO_SERVING = "no_serving"
+"""Serving was not successful. (Rejected from the order manager)
+ 
+Args:
+    counter (ServingWindow): the serving window the player wanted to serve on.
+    item (Item): the item that cannot be serves (now still on the player's hand).
+    env_time (datetime): current env time.
+    player (str): the player id.
+"""
 
 PLATE_OUT_OF_KITCHEN_TIME = "plate_out_of_kitchen_time"
+"""A plate is out of the kitchen (after successful serving).
+
+Args:
+    time_plate_to_add (datetime): the time the plate will arrive back in the kitchen
+"""
 DIRTY_PLATE_ARRIVES = "dirty_plate_arrives"
+"""A plate arrived at the kitchen (some time after serving)
+
+Args:
+    counter (Counter): 
+"""
 
 TRASHCAN_USAGE = "trashcan_usage"
+"""Successful usage of the trashcan.
+
+Args:
+    counter (Trashcan): the trashcan used.
+    item (Item): the item the player holding. (If it is a `CookingEquipmeent` only content_list is removed).
+    player (str): the player id.
+"""
 
 ADDED_PLATE_TO_SINK = "added_plate_to_sink"
+"""Dirty Plate dropped on the sink.
+
+Args:
+    counter (Sink): the sink, target of the drop off.
+    item (Plate): the dirty plate.
+    player (str): the player id.
+"""
 DROP_ON_SINK_ADDON = "drop_on_sink_addon"
+"""Something is dropped on the sink addon and combined with the top plate.
+
+Args:
+    counter (SinkAddon): the target counter of the drop off.
+    item (Item): the item which is combined with the top plate.
+    player (str): the player id.
+"""
 PICK_UP_FROM_SINK_ADDON = "pick_up_from_sink_addon"
+"""Player picks up the top plate.
+
+Args:
+    player (str): the player id.
+    occupied_by (Plate): the top plate that is picked up.
+    counter (SinkAddon): the counter class from it picked up.
+"""
 PLATE_CLEANED = "plate_cleaned"
+"""The player finished cleaning a plate.
+
+Plate is transferred to the SinkAddon afterwards.
+
+Args:
+    counter (Sink): The sink on which the plate was cleaned.
+    player (str): the player id.
+"""
+
+# --- items.py ---
 
 ON_ITEM_TRANSITION = "on_item_transition"
+"""A new Effect appears (Fire starts).
+
+Args:
+    item (CookingEquipment): the pot, pan, ... on which the fire starts.
+    result (Effect): the fire effect that is now active on the equipment.
+    seconds (float/int): how long it took to create the fire.
+"""
 CONTENT_READY = "content_ready"
+"""A meal is ready on a cooking equipment.
+
+Args:
+    result (str): Name of the meal.
+    before (CookingEquipment): the cooking equipment.
+"""
 
 # --- orders.py ---
 
 SERVE_NOT_ORDERED_MEAL = "serve_not_ordered_meal"
+"""If a meal does not match to an order but `serve_not_ordered_meals`is active.
+
+Args:
+    meal (Item): the meal that is served.
+    meal_name (str): equivalent to meal.name. The name of the meal.
+"""
 SERVE_WITHOUT_PLATE = "serve_without_plate"
+"""Somehow tried to serve without a plate. Will not be served.
+
+Args:
+    item (Item): The item that the player has in his hands.
+"""
 
-ORDER_DURATION_SAMPLE = "order_duration_sample"
 COMPLETED_ORDER = "completed_order"
+"""A meal was served that completed an order.
+
+Args:
+    order (Order): the order that was fulfilled.
+    meal (Item): The meal that was served.
+    relative_order_time (timedelta): the time that the player needed to fulfill the order.
+    meal_name (str): name of the meal.
+"""
 INIT_ORDERS = "init_orders"
+"""The initial orders were generated.
+
+Args:
+    init_orders (list[Order]): the init orders.
+"""
 NEW_ORDERS = "new_orders"
+"""New orders (not init orders) were generated.
+
+Args:
+    new_orders (list[Order]): the new orders.
+"""
 ORDER_EXPIRED = "order_expired"
+"""An order expired (took too long).
+
+Args:
+    order (Order): the order that expired.
+"""
 
 # --- environment.py --- but player related.
 
 ACTION_ON_NOT_REACHABLE_COUNTER = "action_on_not_reachable_counter"
+"""Player wants to interact or pick/drop but no counter is in reach.
+
+Args:
+    action (Action): the action with the player id.
+    counter (Counter): closest but not reachable counter.
+"""
 ACTION_PUT = "action_put"
+"""Player does the put (pick or drop) action
+
+Args:
+    action (Action): the action with the player id.
+    counter (Counter): on which the put action is performed.
+"""
 ACTION_INTERACT_START = "action_interact_start"
+"""Player starts interacting on a counter.
+
+Args:
+    action (Action): the action with the player id
+    counter (Counter): on which the player starts the interaction.
+"""
 
 # --- effects.py ---
 
 ITEM_BURNED = "item_burned"  # MISSING
+"""NOT IMPLEMENTED"""
 NEW_FIRE = "new_fire"
+"""New fire from cooking equipment (Does not include spreading).
+
+Args:
+    target (Counter|Item): on which the fire was created.
+"""
 FIRE_SPREADING = "fire_spreading"
+"""Fire spreads on other counter/items after some time.
+
+Args:
+        target (Counter|Item): on which the fire is spreading.
+"""
 
 # --- movement.py ---
 
 PLAYERS_COLLIDE = "players_collide"
+"""Every frame player collides.
+
+Args:
+    collisions (npt.NDArray[bool]): the players which collide.
+"""
 
 # --- players.py ---
 
 PLAYER_START_INTERACT = "player_start_interaction"
+"""Same as `ACTION_INTERACT_START` but in the player.py
+
+Args:
+    player (str): the player id.
+    counter (Counter): the last interacted counter.
+"""
 PLAYER_END_INTERACT = "player_end_interact"
+"""The interaction with a counter stopped. Either stopped by the player through button press or move away.
+
+Args:
+    player (str): the player id.
+    counter (Counter): the last interacted counter.
+"""
 
 
 class Hooks:

cooperative_cuisine/orders.py

@@ -51,7 +51,6 @@ from cooperative_cuisine.hooks import (
     COMPLETED_ORDER,
     INIT_ORDERS,
     NEW_ORDERS,
-    ORDER_DURATION_SAMPLE,
     ORDER_EXPIRED,
 )
 from cooperative_cuisine.items import Item, Plate, ItemInfo
@@ -248,7 +247,7 @@ class OrderManager:
     def create_init_orders(self, env_time):
         """Create the initial orders in an environment."""
         init_orders = self.order_gen.init_orders(env_time)
-        self.hook(INIT_ORDERS)
+        self.hook(INIT_ORDERS, init_orders=init_orders)
         self.open_orders.extend(init_orders)
 
         # self.update_next_relevant_time()
@@ -495,10 +494,6 @@ class RandomOrderGeneration(OrderGeneration):
                         **self.kwargs.order_duration_random_func["kwargs"]
                     )
                 duration = timedelta(seconds=seconds)
-            self.hook(
-                ORDER_DURATION_SAMPLE,
-                duration=duration,
-            )
             log.info(f"Create order for meal {meal} with duration {duration}")
             orders.append(
                 Order(

cooperative_cuisine/pygame_2d_vis/drawing.py

@@ -1021,12 +1021,11 @@ def generate_recipe_images(config: dict, folder_path: str | Path):
 
 
 def main(args):
-    """
-
-    Runs the Cooperative Cuisine Image Generation process.
+    """Runs the Cooperative Cuisine Image Generation process.
 
-    This method takes command line arguments to specify the state file, visualization configuration file, and output file for the generated image. It then reads the visualization configuration
-    * file and state file, and calls the 'save_screenshot' and 'generate_recipe_images' methods to generate the image.
+    This method takes command line arguments to specify the state file, visualization configuration file, and output
+    file for the generated image. It then reads the visualization configuration file and state file, and calls the
+    'save_screenshot' and 'generate_recipe_images' methods to generate the image.
 
     Args:
         -s, --state: A command line argument of type `argparse.FileType("r", encoding="UTF-8")`. Specifies the state file to use for image generation. If not provided, the default value is 'ROOT_DIR / "pygame_2d_vis" / "sample_state.json"'.