# 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 sequence frame images
- Customizable animation playback speed
- Support alias management for multiple sets of animations
- Automatic loop playback
- Built-in help() function
- New feature: Smooth movement
- New feature: Reverse playback
- New feature: Get the status of the animation

## Install Dependencies
```bash
pip install pygame
```

## Quick Start
```python
import pygame
from Animation import Animation, AnimationSprite

# Sprite class (ensures correct initialization)
class Player(pygame.sprite.Sprite, AnimationSprite):
    def __init__(self, x, y):
        pygame.sprite.Sprite.__init__(self)
        AnimationSprite.__init__(self)

        # Sprite image
        self.image = pygame.Surface((50, 50))
        self.image.fill((0, 255, 0))
        self.rect = self.image.get_rect(center=(x, y))

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


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

# Create sprite
player = Player(400, 300)
group = pygame.sprite.Group()
group.add(player)

# Start moving automatically on run
player.move_to_position_in(100, 100, 150)

# Main loop
running = True
while running:
    # 1. Clear screen
    screen.fill((0, 0, 0))

    # Event handling
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    # 2. Update animation (must be called before draw)
    player.update_animation()

    # 3. Draw elements
    group.draw(screen)

    Animation.image_show("player_walk", 200, 300, screen)

    Animation.animation_start("player_walk", 4)

    # 4. Refresh screen (final step)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()
```

## Function Description (Key Partial Functions)
### add_file_path
Register animation file path and alias
```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 animation
```python
def animation_start(alias: str, count: int, add_underline: bool = True, file_type: str = "png")
```

### animation_stop
Stop animation playback
```python
def animation_stop(alias : str)
```

### set_animation_frame
Set the current animation frame
```python
def set_animation_frame(alias : str, frame : int = 1)
```

### set_animation_speed
Set the animation playback speed
```python
def set_animation_speed(alias : str, speed : int = 2)
```

### animation_reverse
Reverse animation playback
```python
def animation_reverse(alias : str)
```

### animation_reverse_back
Restore animation playback
```python
def animation_reverse_back(alias : str)
```

## AnimationSprite
This class is currently used to implement the "slide in (x:(), y:()) in (seconds)" function in the Scratch.
It will be further developed to implement more functions.

## AnimationStatus
    This class is used to get the status of the animation.
    For example:
        Animation.AnimationStatus("player_walk").get_settings() # Returns the animation settings in json format
        Animation.AnimationStauts("player_walk").get_status("")
        In this case, you can fill in:
            "animation_started", 
            "image_showing", 
            "animation_start", 
            "animation_end", 
            "animation_reverse"
        These status information.

    Parameters:
        alias: alias

    Raises:
        NotFoundAliasError - alias not found.
```python
- def get_status(status : Literal["animation_started", 
                                          "image_showing", 
                                          "animation_start", 
                                          "animation_end", 
                                          "animation_reverse"])
```


## Exception Types
- NotFoundFileError: File does not exist
- UnboundWindowError: Window not bound
- ImageNotShowError: Image not displayed
- NotFoundAliasError: Animation alias not found
- ValueError: Thrown when input data is invalid
- TypeError: Type mismatch error

## Notice
- Further updates may be released later, suggestions are welcome
- QQ Email: watermeloncode@foxmail.com
- Version 2 released on 2026.5.3
  - Base class available: classes can inherit AnimationSprite
  - Added smooth movement feature
  - Added reverse playback feature
  - Added get the status of the animation
  - Added example: 'run-Animation-example' to execute example
- Version 1 released on 2026.5.2

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



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

## 功能
- 加载序列帧图片
- 自定义动画播放速度
- 支持别名管理多组动画
- 自动循环播放
- 内置 help() 函数
- 新增：平滑移动
- 新增：倒序播放动画
- 新增：可获取动画的当前状态

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

## 快速使用
```python
import pygame
from Animation import Animation, AnimationSprite

# 精灵类（保证初始化正确）
class Player(pygame.sprite.Sprite, AnimationSprite):
    def __init__(self, x, y):
        pygame.sprite.Sprite.__init__(self)
        AnimationSprite.__init__(self)

        # 精灵图片
        self.image = pygame.Surface((50, 50))
        self.image.fill((0, 255, 0))
        self.rect = self.image.get_rect(center=(x, y))

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


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

# 创建精灵
player = Player(400, 300)
group = pygame.sprite.Group()
group.add(player)

# 一运行就自动开始移动
player.move_to_position_in(100, 100, 150)

# 主循环
running = True
while running:
    # 1. 清屏
    screen.fill((0, 0, 0))

    # 事件
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    # 2. 更新动画（必须写在 draw 前面）
    player.update_animation()

    # 3. 绘制
    group.draw(screen)

    Animation.image_show("player_walk", 200, 300, screen)

    Animation.animation_start("player_walk", 4)

    # 4. 刷新屏幕（最后一步）
    pygame.display.flip()
    clock.tick(60)

pygame.quit()
```

## 函数说明（部分重要的函数）
### 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")
```

### animation_stop
停止动画播放
```python
def animation_stop(alias : str)
```

### set_animation_frame
设置动画当前帧
```python
def set_animation_frame(alias : str, frame : int = 1)
```

### set_animation_speed
设置动画播放速度
```python
def set_animation_speed(alias : str, speed : int = 2)
```

### animation_reverse
反转动画播放
```python
def animation_reverse(alias : str)
```

### animation_reverse_back
恢复动画播放
```python
def animation_reverse_back(alias : str)
```

### AnimationSprite
这个类目前是实现了类Scratch中“在（）秒内滑行到x:()，y:()”的功能。
后续会继续完善这个类，使其能够实现更多的功能。

### AnimationStatus
这个类用于获取动画的状态。
        例如：
            Animation.AnimationStatus("player_walk").get_settings() # 返回json格式的动画设置
            Animation.AnimationStauts("player_walk").get_status("")
            在这里可以填：
                "animation_started", 
                "image_showing", 
                "animation_start", 
                "animation_end", 
                "animation_reverse"
            这些状态信息。

        参数：
            alias： 别名

        引发：
            NotFoundAliasError - 别名不存在。
```python
- get_settings(): 
```
这个函数返回的是一个json格式的字符串，包含了动画的大部分信息。
```python
- def get_status(status : Literal["animation_started", 
                                          "image_showing", 
                                          "animation_start", 
                                          "animation_end", 
                                          "animation_reverse"])
```
这个函数返回的是当前动画的一些状态信息。
        比如：
            animation_started -> bool
            image_showing -> bool
            animation_start -> bool
            animation_end -> bool
            animation_reverse -> bool


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

## 消息
- 后续可能会继续更新，欢迎提出建议
- QQ邮箱：watermeloncode@foxmail.com
- 2026.5.3 发布第二个版本
  - 基类，class可继承 AnimtionSprite
  - 新增平滑移动
  - 新增倒序播放动画
  - 新增获取动画状态
  - 使用示例：'run-Animation-example' 来执行示例
- 2026.5.2 发布第一个版本

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