game/progression.py

"""Progression goals for Myco's collectible forest loop."""

from dataclasses import dataclass


@dataclass(frozen=True)
class AreaUnlock:
    """A forest area unlocked by MycoDex progress."""

    name: str
    required_discoveries: int
    description: str


@dataclass(frozen=True)
class MysteryThread:
    """A story clue revealed through exploration instead of generic XP."""

    name: str
    required_discoveries: int
    clue: str


AREA_UNLOCKS: tuple[AreaUnlock, ...] = (
    AreaUnlock("Mossy Trail", 0, "Myco's favorite beginner path, full of soft moss and gentle spores."),
    AreaUnlock("Crystal Grove", 10, "A glittering grove where rare caps grow beside singing stones."),
    AreaUnlock("Moonlit Cavern", 25, "A blue-lit cave where legendary fungi bloom after midnight."),
    AreaUnlock("Mushroom Elder", 50, "The hidden elder of the forest, waiting for a true MycoDex keeper."),
)

MYSTERY_THREADS: tuple[MysteryThread, ...] = (
    MysteryThread("First Spore", 1, "A brown cap points toward an unseen door under the roots."),
    MysteryThread("Whispering Ring", 3, "Three collected fungi form a ring that hums when Myco gets close."),
    MysteryThread("Star Hollow", 7, "Rare mushrooms start leaving silver dust near the northern trees."),
    MysteryThread("Elder Map", 12, "Legendary fungi reveal fragments of a map only Myco can read."),
)


def unlocked_areas(discovery_count: int) -> tuple[AreaUnlock, ...]:
    """Return every area unlocked by the current MycoDex count."""
    return tuple(area for area in AREA_UNLOCKS if discovery_count >= area.required_discoveries)


def current_area(discovery_count: int) -> AreaUnlock:
    """Return the highest unlocked area for a discovery count."""
    return unlocked_areas(discovery_count)[-1]


def next_area(discovery_count: int) -> AreaUnlock | None:
    """Return the next locked area, if any."""
    for area in AREA_UNLOCKS:
        if discovery_count < area.required_discoveries:
            return area
    return None


def revealed_mysteries(discovery_count: int) -> tuple[MysteryThread, ...]:
    """Return story secrets revealed by the current MycoDex count."""
    return tuple(thread for thread in MYSTERY_THREADS if discovery_count >= thread.required_discoveries)


def next_mystery(discovery_count: int) -> MysteryThread | None:
    """Return the next story secret the player is working toward."""
    for thread in MYSTERY_THREADS:
        if discovery_count < thread.required_discoveries:
            return thread
    return None