freepygame 0.1.1

A Pygame UI controls library providing buttons, text, circles and other widgets

freepygame

一个为 Pygame 游戏开发提供 UI 控件和工具的 Python 库。

特性

• 🎨 丰富的 UI 组件: 按钮、文本、圆形、图标等
• 🖌️ 抗锯齿支持: 高质量图形渲染
• 🔧 易于使用: 简单的 API 和直观的接口
• 🎯 灵活配置: 支持颜色、大小、位置等属性动态调整
• ✨ 特效支持: 粒子系统、图像处理等高级功能
• 📱 缩放支持: 支持高DPI显示和界面缩放

安装

pip install freepygame

或者从源代码安装:

git clone https://github.com/freebird/freebPygame.git
cd freebPygame
pip install -e .

快速开始

import pygame
from freepygame import FreeButton, FreeText, position_button_class

# 初始化 Pygame
pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

# 创建按钮
button = FreeButton(
    screen=screen,
    coordinates=[100, 100],
    button_size=[200, 50],
    msg="点击我",
    button_color=(70, 130, 180),
    text_color=(255, 255, 255)
)

# 创建文本
text = FreeText(
    screen=screen,
    coordinates=[100, 170],
    msg="欢迎使用 freepygame!",
    color=(0, 0, 0)
)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.MOUSEBUTTONDOWN:
            if position_button_class(button, pygame.mouse.get_pos()):
                text.set_msg("按钮被点击了!")
    
    # 绘制
    screen.fill((240, 240, 245))
    button.draw()
    text.draw()
    
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

主要组件

按钮组件

FreeButton - 矩形按钮

button = FreeButton(
    screen=screen,
    coordinates=[x, y],          # 左上角坐标
    button_size=[width, height], # 按钮尺寸
    msg="按钮文本",              # 显示文本
    button_color=(r, g, b),      # 按钮背景色
    text_color=(r, g, b),        # 文本颜色
    draw_border=True,            # 是否显示边框
    border_width=2,              # 边框宽度
    dsm=1                        # 缩放系数
)

CircleButton - 圆形按钮

circle_btn = CircleButton(
    screen=screen,
    coordinates=[x, y],          # 圆心坐标
    radius=50,                   # 半径
    msg="圆形按钮",              # 显示文本
    button_color=(r, g, b),      # 按钮颜色
    msg_color=(r, g, b)          # 文本颜色
)

文本组件

FreeText - 基础文本

text = FreeText(
    screen=screen,
    coordinates=[x, y],          # 文本位置
    msg="文本内容",              # 显示文本
    font=None,                   # 字体文件路径或 Pygame 字体对象
    size=24,                     # 字体大小
    color=(r, g, b)              # 文本颜色
)

SuperText - 超级文本（支持缩放）

super_text = SuperText(
    screen=screen,
    coordinates=[x, y],
    msg="支持缩放的文本",
    size=24,
    color=(r, g, b),
    dsm=1.5  # 1.5倍缩放
)

图形组件

FreeCircle - 圆形/弧形

circle = FreeCircle(
    screen=screen,
    coordinates=[x, y],          # 圆心坐标
    radius=50,                   # 半径
    width=2,                     # 线宽（0为实心）
    angle=(0, 360),              # 角度范围（用于绘制弧）
    aa=True,                     # 是否抗锯齿
    color=(r, g, b)              # 颜色
)

FreeAllCircle - 静态绘图方法

# 绘制抗锯齿圆
FreeAllCircle.draw_aacircle(screen, (x, y), radius, color)

# 绘制贝塞尔曲线
points = [(100, 100), (200, 50), (300, 150), (400, 100)]
FreeAllCircle.draw_bezier(screen, points, steps=100, color=(128, 128, 128))

其他组件

FreeIcon - 图标

icon = FreeIcon(
    screen=screen,
    coordinates=[x, y],          # 图标位置
    image_1=normal_image,        # 正常状态图像
    image_2=hover_image          # 悬停状态图像
)

# 切换图标状态
icon.set_index(0)  # 显示 image_1
icon.set_index(1)  # 显示 image_2

ParticleEngine - 粒子系统

engine = ParticleEngine()

# 生成粒子
engine.generate_particles(50, (x, y))

# 更新粒子
engine.update_particles()

# 绘制粒子
engine.draw_particles(screen)

图像处理

from freepygame import image_blur_processing, array_mean_rgba

# 图像模糊处理
blurred_image = image_blur_processing(image, level=2)

# 计算图像区域的平均颜色
avg_color = array_mean_rgba(pixel_data)

实用函数

点击检测

# 检测点是否在按钮内
if position_button(rect, pos):
    print("点在矩形内")

# 检测点是否在按钮对象内
if position_button_class(button, pos):
    print("点在按钮内")

高级特性

操作符重载

SuperText 的操作符

text = SuperText(screen, [100, 100], "Hello")

# << 操作符快捷设置属性
text << (36,)           # 设置字体大小
text << (200, 150)      # 设置位置
text << (255, 0, 0)     # 设置颜色

# + 操作符拼接文本
text + " World!"        # 文本变为 "Hello World!"

SuperCircle 的操作符

circle = SuperCircle(screen, [400, 300], 50)

circle << (75,)         # 设置半径
circle << ((80, 60),)   # 设置长短半轴
circle << ((255, 0, 0),) # 设置颜色

示例

查看 examples/ 目录获取完整示例：

• basic_demo.py - 基础演示程序
• particle_demo.py - 粒子系统演示
• ui_demo.py - 完整UI界面演示

运行示例：

cd examples
python basic_demo.py

项目结构

freepygame/
├── freepygame/          # 主包目录
│   ├── __init__.py     # 包初始化
│   ├── freebutton.py   # 按钮组件
│   ├── freecircle.py   # 圆形组件
│   ├── freetext.py     # 文本组件
│   ├── freeicon.py     # 图标组件
│   ├── freeparticle.py # 粒子系统
│   ├── freetransformation.py # 图像处理
│   └── freepygamelib.py # 单文件版本
├── tests/              # 测试目录
│   ├── conftest.py    # 测试配置
│   ├── test_components/ # 组件测试
│   └── test_integration/ # 集成测试
├── examples/           # 示例目录
├── setup.py           # 安装配置
├── README.md          # 本文档
└── LICENSE.txt        # 许可证文件

许可证

本项目采用 Apache License 2.0 许可证。详见 LICENSE.txt。

贡献

欢迎提交 Issue 和 Pull Request！

作者

freebird

致谢

• Pygame - 游戏开发库

---

注意: 本库仍在积极开发中，API 可能会有变动。