Skip to content

Sprites

Animated sprite classes for player and NPC characters.

Location

src/pedre/sprites/

AnimatedPlayer

Player character sprite with 4-directional animation.

Constructor

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:

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:

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

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

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

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

See Also