# Animation 2D Frame Animation Library
A lightweight 2D sprite frame animation library developed based on Pygame. It is concise and easy to use, enabling quick implementation of character animation playback. It also has a built-in help function; call the `animation_help()` function to get assistance.

## Features
- Load sprite frame images
- Customize animation playback speed
- Support alias management for multiple sets of animations
- Automatic loop playback
- Complete exception prompts and colored logs

## Dependency Installation
```bash
pip install pygame
```

## Quick Start
```python
import pygame
import Animation

pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

Animation.add_file_path(r"D:\image\player_walk_1.png", "player_walk", 10)

while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            exit()

    screen.fill((255, 255, 255))
    Animation.animation_start("player_walk", 3)
    Animation.image_show("player_walk", 100, 100, screen)

    pygame.display.update()
    clock.tick(60)
```

## Function Description (Key Partial Functions)
### add_file_path
Register animation file paths and aliases
```python
def add_file_path(file_path: str, alias: str, wait: int)
```

### image_show
Display the current animation frame at a specified position on the window
```python
def image_show(alias: str, x: int, y: int, window: pygame.Surface)
```

### animation_start
Drive automatic frame switching for animations
```python
def animation_start(alias: str, count: int, add_underline: bool = True, file_type: str = "png")
```

## Exception Types
- NotFoundFileError:  The file does not exist
- UnboundWindowError: Window not bound
- ImageNotShowError:  Image not displayed
- NotFoundAliasError: Animation alias not found
- ValueError: Thrown  when the input data is invalid

## Notices
- Further updates may be released in the future, suggestions are welcome
- QQ Email: watermeloncode@foxmail.com
- First version released on 2026.5.2

## Author
WatermelonJuiceCode
Bilibili: WatermelonJuiceCode
WeChat: WatermelonJuiceCode
QQ: 3931840613



# Animation 2D 帧动画库
基于 Pygame 开发的轻量级 2D 序列帧动画库，简洁易用，快速实现角色动画播放。
以及拥有内置的寻求帮助，使用 animation_help() 函数去寻求帮助。

## 功能
- 加载序列帧图片
- 自定义动画播放速度
- 支持别名管理多组动画
- 自动循环播放
- 完善异常提示与彩色日志

## 安装依赖
```bash
pip install pygame
```

## 快速使用
```python
import pygame
import Animation

pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

Animation.add_file_path(r"D:\image\player_walk_1.png", "player_walk", 10)

while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            exit()

    screen.fill((255, 255, 255))
    Animation.animation_start("player_walk", 3)
    Animation.image_show("player_walk", 100, 100, screen)

    pygame.display.update()
    clock.tick(60)
```

## 函数说明（部分重要的函数）
### add_file_path
注册动画文件路径与别名
```python
def add_file_path(file_path: str, alias: str, wait: int)
```

### image_show
在窗口指定位置显示当前动画帧
```python
def image_show(alias: str, x: int, y: int, window: pygame.Surface)
```

### animation_start
驱动动画自动切换帧
```python
def animation_start(alias: str, count: int, add_underline: bool = True, file_type: str = "png")
```

## 异常类型
- NotFoundFileError： 文件不存在
- UnboundWindowError：未绑定窗口
- ImageNotShowError： 图片未显示
- NotFoundAliasError：未找到动画别名
- ValueError：        填写的数据不符合事实时抛出

## 消息
- 后续可能会继续更新，欢迎提出建议
- QQ邮箱：watermeloncode@foxmail.com
- 2026.5.2 发布第一个版本

## 作者
西瓜汁Code
B站：西瓜汁Code
微信：WatermelonJuiceCode
QQ：3931840613
```