"""Base class for InventoryPlugin."""

from abc import ABC, abstractmethod
from dataclasses import dataclass

from pedre.plugins.base import BasePlugin


@dataclass
class InventoryItem:
    """Represents a collectible item in the player's inventory.

    An InventoryItem contains all the metadata needed to display and track a collectible
    item in the game. Items are defined with their content (name, description, image) and
    state (whether the player has acquired it).

    The dataclass structure makes items easy to define in code or load from data files.
    Items are typically created during game initialization and added to the InventoryPlugin,
    where they persist throughout the game session.

    The 'acquired' flag determines whether the player currently possesses the item. Items
    can be pre-acquired (starting inventory) or start unacquired and be collected during
    gameplay. This allows for collectathon gameplay where players track their progress
    toward finding all items.

    Attributes:
        id: Unique identifier for this item (e.g., "secret_key", "photo_01").
           Used for lookups, save data, and script references. Should be lowercase
           with underscores for consistency.
        name: Display name shown to the player (e.g., "Rusty Key", "Family Photo").
             Can be in any language and include special characters for presentation.
        description: Flavor text or description shown when examining the item.
                    Can be multiple sentences providing context or story information.
        image_path: Optional path to the item's full-size image file, relative to assets/images/.
                   For example, "items/key.png" or "photos/memory_01.jpg". Set to None
                   for items without visual representation. This is displayed when viewing
                   the item in detail (e.g., full-screen photo view).
        icon_path: Optional path to the item's icon/thumbnail image, relative to assets/images/.
                  For example, "icons/key_icon.png" or "photos/thumbs/memory_01_thumb.jpg".
                  This is displayed in the inventory grid as a preview. If None, the grid
                  slot will be empty (just the background color). Default is None.
        category: Item category for filtering and organization. Common categories include
                 "photo", "note", "key", "potion", "general". Categories are user-defined strings
                 and can be extended as needed. Used for script filtering and applying effects.
                 Default is "general".
        acquired: Whether the player has collected this item. True means the item is in
                 the player's possession, False means it hasn't been found yet. Can be
                 set to True initially for starting items. Default is False.
        consumed: Whether the item has been consumed/used. Consumed items don't appear in
                 the inventory display. Default is False.
        consumable: Whether the item can be consumed from the inventory overlay UI. When True,
                   the player can press the consume key (default: C) to consume the item, which
                   triggers an ItemConsumedEvent. Default is False.

    Example:
        # A collectible photograph with icon
        photo = InventoryItem(
            id="beach_memory",
            name="Beach Day",
            description="A sunny day at the coast with friends.",
            image_path="photos/beach.jpg",
            icon_path="photos/icons/beach_icon.png",
            category="photo",
            acquired=False
        )

        # A key item for progression
        key = InventoryItem(
            id="tower_key",
            name="Tower Key",
            description="Opens the old tower door.",
            image_path="items/tower_key.png",
            icon_path="items/icons/key_icon.png",
            category="key",
            acquired=True  # Player starts with this
        )
    """

    id: str  # Unique identifier
    name: str  # Display name
    description: str  # Item description
    image_path: str | None = None  # Path to full-size image file (relative to assets/images/)
    icon_path: str | None = None  # Path to icon/thumbnail image (relative to assets/images/)
    category: str = "general"  # Item category (photo, note, key, etc.)
    acquired: bool = False  # Whether the player has this item
    consumed: bool = False  # Whether the item has been consumed/used
    consumable: bool = False  # Whether the item can be consumed from the inventory overlay


class InventoryBasePlugin(BasePlugin, ABC):
    """Base class for InventoryPlugin."""

    role = "inventory_plugin"

    @abstractmethod
    def has_been_accessed(self) -> bool:
        """Check if inventory has been accessed."""
        ...

    @abstractmethod
    def has_item(self, item_id: str) -> bool:
        """Check if the player has acquired a specific item."""
        ...

    @abstractmethod
    def acquire_item(self, item_id: str) -> bool:
        """Mark an item as acquired by the player."""
        ...

    @abstractmethod
    def consume_item(self, item_id: str) -> bool:
        """Mark an item as consumed by the player."""
        ...

    @abstractmethod
    def add_item(self, item: InventoryItem) -> bool:
        """Add a new item to the inventory plugin and optionally acquire it."""
        ...
