"""Animated player sprite with 4-directional movement.

This module provides an animated sprite class for the player character with support
for idle and walking animations in all four cardinal directions. The sprite loads
animation frames from a sprite sheet and handles frame progression based on movement
state.

Key features:
- Idle and walk animations for all four directions (up, down, left, right)
- Optional animations - specify only the directions you need
- Automatic texture flipping for left-facing animations (mirrors right direction)
- Configurable animation speeds and frame counts per direction
- Delta time-based animation for smooth playback
- Simple API for movement control

The sprite sheet format expects animations laid out in rows:
- Each row contains frames for one animation type and direction
- Frames are ordered left-to-right in the sprite sheet
- Tile size determines the dimensions of each frame
- Left-facing animations can be auto-generated by flipping right-facing frames

Unlike AnimatedNPC, AnimatedPlayer does not support special animations like appear,
disappear, or interact. This keeps the player sprite simple and focused on core
movement functionality.

Example usage:
    # Create player with all 4 directions
    player = AnimatedPlayer(
        "assets/characters/player.png",
        idle_up_frames=4, idle_up_row=0,
        idle_down_frames=4, idle_down_row=1,
        idle_right_frames=4, idle_right_row=2,
        walk_up_frames=6, walk_up_row=4,
        walk_down_frames=6, walk_down_row=5,
        walk_right_frames=6, walk_right_row=6,
        scale=2.0,
        center_x=512,
        center_y=384
    )

    # Update animation each frame
    player.update_animation(delta_time, is_moving)

    # Change direction
    player.set_direction("down")
"""

import logging
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pathlib import Path
from pedre.conf import settings
from pedre.sprites.animated_sprite import AnimatedSprite

logger = logging.getLogger(__name__)


class AnimatedPlayer(AnimatedSprite):
    """Player sprite with walking animations for all four cardinal directions.

    Extends AnimatedSprite with player-specific behavior. Currently, this class
    doesn't add additional functionality beyond the base class, but it exists as
    a separate class to allow for future player-specific features and to maintain
    clear separation between player and NPC sprites.

    Unlike AnimatedNPC, this class does not include special animations (appear, disappear,
    interact) to keep the player character implementation simple and focused on movement.

    Attributes:
        Inherits all attributes from AnimatedSprite:
        - tile_size: Size of each frame in the sprite sheet (pixels).
        - current_direction: Current facing direction ("up", "down", "left", or "right").
        - current_frame: Current frame index in the active animation.
        - animation_speed: Time between animation frames in seconds.
        - animation_timer: Accumulator for frame timing.
        - animation_textures: Dictionary mapping animation names to texture lists.

    Animation texture keys:
        - "idle_up", "idle_down", "idle_left", "idle_right": Idle animations for each direction
        - "walk_up", "walk_down", "walk_left", "walk_right": Walking animations for each direction
    """

    def __init__(
        self,
        sprite_sheet_path: Path | str,
        *,
        tile_size: int = settings.TILE_SIZE,
        scale: float = 1.0,
        center_x: float = 0,
        center_y: float = 0,
        # Parameters for 4-directional animations
        idle_up_frames: int | None = None,
        idle_up_row: int | None = None,
        idle_down_frames: int | None = None,
        idle_down_row: int | None = None,
        idle_left_frames: int | None = None,
        idle_left_row: int | None = None,
        idle_right_frames: int | None = None,
        idle_right_row: int | None = None,
        walk_up_frames: int | None = None,
        walk_up_row: int | None = None,
        walk_down_frames: int | None = None,
        walk_down_row: int | None = None,
        walk_left_frames: int | None = None,
        walk_left_row: int | None = None,
        walk_right_frames: int | None = None,
        walk_right_row: int | None = None,
    ) -> None:
        """Initialize the animated player sprite.

        Loads animation textures from a sprite sheet and sets up animation state. All
        animations are optional - specify only the directions you need. At least one
        animation should be specified, otherwise a placeholder texture is created.

        The sprite sheet should be organized with animations in horizontal rows. Each row
        contains sequential frames for one animation type and direction.

        Args:
            sprite_sheet_path: Path to the sprite sheet PNG file.
            tile_size: Size of each frame in pixels (width and height). Default is 64x64.
            scale: Sprite scale multiplier for rendering. Default is 1.0.
            center_x: Initial X position in world coordinates.
            center_y: Initial Y position in world coordinates.

            Direction-specific parameters (recommended):
            idle_up_frames: Number of frames in up idle animation.
            idle_up_row: Row index for up idle animation.
            idle_down_frames: Number of frames in down idle animation.
            idle_down_row: Row index for down idle animation.
            idle_left_frames: Number of frames in left idle animation.
            idle_left_row: Row index for left idle animation.
            idle_right_frames: Number of frames in right idle animation.
            idle_right_row: Row index for right idle animation.
            walk_up_frames: Number of frames in up walk animation.
            walk_up_row: Row index for up walk animation.
            walk_down_frames: Number of frames in down walk animation.
            walk_down_row: Row index for down walk animation.
            walk_left_frames: Number of frames in left walk animation.
            walk_left_row: Row index for left walk animation.
            walk_right_frames: Number of frames in right walk animation.
            walk_right_row: Row index for right walk animation.

        Example:
            # 4-directional player with all animations
            player = AnimatedPlayer(
                "assets/player.png",
                idle_up_frames=4, idle_up_row=0,
                idle_down_frames=4, idle_down_row=1,
                idle_right_frames=4, idle_right_row=2,
                idle_left_frames=4, idle_left_row=3,
                walk_up_frames=6, walk_up_row=4,
                walk_down_frames=6, walk_down_row=5,
                walk_left_frames=6, walk_left_row=6,
                walk_right_frames=6, walk_right_row=7,
                scale=2.0
            )
        """
        super().__init__(
            sprite_sheet_path,
            tile_size=tile_size,
            scale=scale,
            center_x=center_x,
            center_y=center_y,
            idle_up_frames=idle_up_frames,
            idle_up_row=idle_up_row,
            idle_down_frames=idle_down_frames,
            idle_down_row=idle_down_row,
            idle_left_frames=idle_left_frames,
            idle_left_row=idle_left_row,
            idle_right_frames=idle_right_frames,
            idle_right_row=idle_right_row,
            walk_up_frames=walk_up_frames,
            walk_up_row=walk_up_row,
            walk_down_frames=walk_down_frames,
            walk_down_row=walk_down_row,
            walk_left_frames=walk_left_frames,
            walk_left_row=walk_left_row,
            walk_right_frames=walk_right_frames,
            walk_right_row=walk_right_row,
        )
