# Sprites

Animated sprite classes for player and NPC characters.

## Location

[src/pedre/sprites/](https://github.com/msaizar/pedre/blob/main/src/pedre/sprites/)

## AnimatedPlayer

Player character sprite with 4-directional animation.

### Constructor

```python
from pedre.sprites import AnimatedPlayer

player = AnimatedPlayer(
    sprite_sheet_path="characters/player.png",
    tile_size=32,
    scale=2.0,
    center_x=320,
    center_y=240,
    # Idle animations
    idle_up_frames=4, idle_up_row=0,
    idle_down_frames=4, idle_down_row=1,
    idle_left_frames=4, idle_left_row=2,
    idle_right_frames=4, idle_right_row=3,
    # Walk animations
    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
)
```

**Parameters:**

- `sprite_sheet_path` (str) - Path to sprite sheet image relative to assets
- `tile_size` (int) - Size of each sprite frame in pixels
- `scale` (float) - Sprite scale multiplier
- `center_x` (float) - Initial X position
- `center_y` (float) - Initial Y position
- `idle_*_frames` (int) - Number of frames for each idle direction animation
- `idle_*_row` (int) - Row index in sprite sheet for each idle direction
- `walk_*_frames` (int) - Number of frames for each walk direction animation
- `walk_*_row` (int) - Row index in sprite sheet for each walk direction

### Methods

#### update_animation

`update_animation(delta_time: float, moving: bool = False) -> None`

Update sprite animation state.

**Parameters:**

- `delta_time` (float) - Time elapsed since last update
- `moving` (bool) - Whether the player is currently moving

**Example:**

```python
player.update_animation(delta_time, moving=True)
```

#### set_direction

`set_direction(direction: str) -> None`

Change facing direction.

**Parameters:**

- `direction` (str) - One of: "up", "down", "left", "right"

**Example:**

```python
player.set_direction("down")
```

### Sprite Sheet Layout

The player sprite sheet should follow this structure:

- **4 directions**: Up, Down, Left, Right
- **2 animation states**: Idle and walking
- **Multiple frames**: Variable per direction (typically 4-8 frames)
- **Consistent size**: All frames must be the same dimensions

### Example Sprite Sheet

```text
Row 0: Idle Up     [frame 0] [frame 1] [frame 2] [frame 3]
Row 1: Idle Down   [frame 0] [frame 1] [frame 2] [frame 3]
Row 2: Idle Left   [frame 0] [frame 1] [frame 2] [frame 3]
Row 3: Idle Right  [frame 0] [frame 1] [frame 2] [frame 3]
Row 4: Walk Up     [frame 0] [frame 1] ... [frame 5]
Row 5: Walk Down   [frame 0] [frame 1] ... [frame 5]
Row 6: Walk Left   [frame 0] [frame 1] ... [frame 5]
Row 7: Walk Right  [frame 0] [frame 1] ... [frame 5]
```

## AnimatedNPC

Non-player character sprite with animation and AI.

### Constructor

```python
from pedre.sprites import AnimatedNPC

npc = AnimatedNPC(
    name="merchant",
    sprite_sheet_path="npc.png",
    tile_size=64,
    columns=12,
    scale=1.0,
    # Idle animations
    idle_up_frames=4, idle_up_row=0,
    idle_down_frames=4, idle_down_row=1,
    idle_left_frames=4, idle_left_row=2,
    idle_right_frames=4, idle_right_row=3,
    # Walk animations
    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,
    # Optional special animations
    appear_frames=9, appear_row=8,
    interact_down_frames=5, interact_down_row=9
)
```

**Parameters:**

- `name` (str) - Unique NPC identifier
- `sprite_sheet_path` (str) - Path to sprite sheet relative to assets
- `tile_size` (int) - Size of each sprite frame in pixels
- `columns` (int) - Total number of columns in sprite sheet
- `scale` (float) - Sprite scale multiplier
- `idle_*_frames` (int) - Frames for idle animations per direction
- `idle_*_row` (int) - Row index for idle animations per direction
- `walk_*_frames` (int) - Frames for walk animations per direction
- `walk_*_row` (int) - Row index for walk animations per direction
- `appear_frames` (int, optional) - Frames for appear animation
- `appear_row` (int, optional) - Row index for appear animation
- `disappear_frames` (int, optional) - Frames for disappear animation
- `disappear_row` (int, optional) - Row index for disappear animation
- `interact_*_frames` (int, optional) - Frames for interact animations per direction
- `interact_*_row` (int, optional) - Row index for interact animations per direction

### Auto-Generated Animations

- If only `appear_*` is defined: `disappear` is auto-generated by reversing appear frames
- If only `disappear_*` is defined: `appear` is auto-generated by reversing disappear frames
- If `interact_left_*` is not specified but `interact_right_*` exists: left is generated by flipping right horizontally

### Attributes

- `name: str` - Unique NPC identifier
- `dialog_level: int` - Current conversation progression level

### Example

```python
# NPC is typically created from Tiled map data
# See NPCPlugin for registration and management
```

## See Also

- [Player Plugin](../plugins/player.md) - PlayerPlugin documentation
- [NPC Plugin](../plugins/npc.md) - NPCPlugin documentation
- [Tiled Integration](../guides/tiled-integration.md) - Setting up sprites in Tiled
