2D-Animation-lib 1.1.0

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

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")

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
• 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")

异常类型

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

消息

• 后续可能会继续更新，欢迎提出建议
• QQ邮箱：[e-mail]
• 2026.5.3 发布第二个版本
  • 基类，class可继承 AnimtionSprite
  • 新增平滑移动
• 2026.5.2 发布第一个版本

作者

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