2D-Animation-lib 1.2.1

A 2D simple animation module for pygame.

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

pip install pygame

Quick Start

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

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

def image_show(alias: str, x: int, y: int, window: pygame.Surface)

animation_start

Drive automatic frame switching for animation

def animation_start(alias: str, count: int, add_underline: bool = True, file_type: str = "png")

animation_stop

Stop animation playback

def animation_stop(alias : str)

set_animation_frame

Set the current animation frame

def set_animation_frame(alias : str, frame : int = 1)

set_animation_speed

Set the animation playback speed

def set_animation_speed(alias : str, speed : int = 2)

animation_reverse

Reverse animation playback

def animation_reverse(alias : str)

animation_reverse_back

Restore animation playback

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: status = AnimationStatus("player_walk") status.get_settings() # Returns the settings of the animation in json format status.get_status("animation_started") # Returns whether the animation has started playing

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: [e-mail]
• 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() 函数
• 新增：平滑移动
• 新增：倒序播放动画
• 新增：可获取动画的当前状态

安装依赖

pip install pygame

快速使用

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

注册动画文件路径与别名

def add_file_path(file_path: str, alias: str, wait: int)

image_show

在窗口指定位置显示当前动画帧

def image_show(alias: str, x: int, y: int, window: pygame.Surface)

animation_start

驱动动画自动切换帧

def animation_start(alias: str, count: int, add_underline: bool = True, file_type: str = "png")

animation_stop

停止动画播放

def animation_stop(alias : str)

set_animation_frame

设置动画当前帧

def set_animation_frame(alias : str, frame : int = 1)

set_animation_speed

设置动画播放速度

def set_animation_speed(alias : str, speed : int = 2)

animation_reverse

反转动画播放

def animation_reverse(alias : str)

animation_reverse_back

恢复动画播放

def animation_reverse_back(alias : str)

AnimationSprite

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

AnimationStatus

这个类用于获取动画的状态。 例如： status = AnimationStatus("player_walk") status.get_settings() # 返回动画的设置 status.get_status("animation_started") # 返回动画是否已经开始播放

    参数：
        alias： 别名

    引发：
        NotFoundAliasError - 别名不存在。

- get_settings(): 

这个函数返回的是一个json格式的字符串，包含了动画的大部分信息。

- 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邮箱：[e-mail]
• 2026.5.3 发布第二个版本
  • 基类，class可继承 AnimtionSprite
  • 新增平滑移动
  • 新增倒序播放动画
  • 新增获取动画状态
  • 使用示例：'run-Animation-example' 来执行示例
• 2026.5.2 发布第一个版本

作者

西瓜汁Code B站：西瓜汁Code 微信：WatermelonJuiceCode QQ：3931840613