🎮 Walimaker - 专为教学设计的Python游戏引擎

Walimaker 是一个专为教学场景设计的Python游戏引擎模块。它采用简洁直观的API设计，让学生能够快速上手游戏开发，同时掌握编程核心概念。模块基于Pygame和Pymunk构建，提供完整的2D游戏开发功能。

✨ 特性亮点

🎯 教学友好

• 简洁API：基于Python语法糖，类似Processing/turtle的直观接口
• 错误友好：详尽的错误提示和调试信息，帮助初学者快速定位问题
• 渐进学习：从简单绘图到复杂游戏逻辑的平滑过渡

🛠 功能完备

• 🎨 图形渲染：精灵动画、位图渲染、TileMap支持
• ⚙️ 物理系统：刚体动力学、碰撞检测、约束系统（基于Pymunk）
• 🎵 音频管理：背景音乐、音效播放、音量控制
• 📝 UI组件：文本框、对话框、按钮等交互元素
• ⌨️ 输入系统：鼠标、键盘、触控事件处理
• 📊 资源管理：智能LRU缓存，自动内存管理

🚀 开发效率

• 热重载：支持代码热更新，快速迭代开发
• 调试工具：内置调试绘制、性能监控、状态查看
• 模块化设计：可扩展的组件系统，易于定制和扩展

🚀 快速开始

安装

通过pip安装

pip install Walimaker

第一个游戏：移动的角色

from Walimaker import *

# 初始化游戏窗口
setup(800, 600)
title("我的第一个Walimaker游戏")

# 创建角色
character = Character(["idle_1.png", "idle_2.png", "idle_3.png"])
character.scale(2, 2)

# 主游戏循环
while True:
    # 事件处理：key_pressed 接收 pygame 的按键常量
    # （K_UP / K_a / K_SPACE 等常量随 `from Walimaker import *` 一起提供）
    if key_pressed(K_UP):
        character.forward(5)
    if key_pressed(K_LEFT):
        character.left(5)
    if key_pressed(K_RIGHT):
        character.right(5)
    if key_pressed(K_SPACE):
        character.say("跳跃！")

    # 动画播放
    character.play_anim()
    
    # 渲染更新
    update()

🧭 中文报错提示（教学特性）

程序出错时，英文原始报错会完整保留（异常类型、消息、完整 traceback），中文解释追加在它的后面， 方便初学者对照着官方报错一起看：

Traceback (most recent call last):
  File "main.py", line 12, in <module>
    if key_pressed(K_SPACE):
NameError: name 'K_SPACE' is not defined

────────────────────────────────────────────────────────────────
【Walimaker 中文提示】按键/事件常量「K_SPACE」没有导入
  原因：pygame 的按键、鼠标、事件常量（K_SPACE、KEYDOWN、QUIT、MOUSEBUTTONDOWN 等）需要先导入才能使用。
  解决：① 确认 walimaker 版本 ≥ 2.1.0（pip install -U walimaker），这些常量会随 from Walimaker import *
        一起提供；② 或者显式写 from pygame.locals import *。
  参考：CHANGELOG 2.1.0「恢复 pygame 事件/按键常量的导出」
────────────────────────────────────────────────────────────────

覆盖的常见错误包括：缺少依赖、变量/函数未定义（按键常量有专项提示）、忘记调用 setup()、 图片/音乐路径找不到、没有声卡、pymunk 坐标类型错误、pymunk 版本兼容问题、key_pressed("w") 传了字符串、 图片类型不支持、setup() 参数不对、Tab 与空格混用、语法/缩进错误、除零、全局变量作用域、递归过深等； 如果报错发生在 Walimaker 自身代码里，会提示"可能是框架问题 + 如何反馈"。

关闭方式（默认开启）：

WALIMAKER_ERROR_HELP=0 python main.py     # 环境变量

set_error_help(False)                     # 或在代码里关闭

在 try/except 里主动取中文解释：

try:
    character = Character("hero.png")
except Exception as e:
    print(explain_exception(e))           # 返回中文解释文本

📁 项目结构

Walimaker/
├── 📄 pyproject.toml        # 打包 / 依赖配置
├── 📄 README.md             # 项目说明
├── 📄 LICENSE               # MIT 许可证
├── 📄 OPTIMIZATION_PLAN.md  # 性能 / 结构分析与优化计划
├── 📁 benchmarks/           # 性能基线脚本（不参与打包）
│   └── 🐍 perf_baseline.py
├── 📁 tests/                # 冒烟 / 回归测试（不参与打包）
│   └── 🐍 smoke_test.py
└── 📁 src/
    └── 📁 Walimaker/        # 包源码（import Walimaker）
        ├── 📄 API.py             # 主要API接口（Character、窗口管理等）
        ├── 📄 sprite.py          # 精灵和动画系统
        ├── ⚙️ physics.py         # 物理引擎封装（基于Pymunk）
        ├── 📷 camera.py          # 相机系统（缩放、跟随）
        ├── 🗺️ tiledmap.py        # TileMap地图系统
        ├── 📝 textbox.py         # UI文本组件
        ├── 🎵 music.py           # 音频管理系统
        ├── 📦 resource_manager.py # 资源管理（智能缓存）
        ├── 🔧 config.py          # 全局配置和初始化
        ├── 🎮 test.py            # 示例代码（walimaker-demo 入口）
        └── 📁 static/            # 资源文件（只有体积很小的图片）
            └── 🖼️ *.png          # 图片资源

关于字体：从 2.3.0 起包内不再携带字体文件（原先的楷体/宋体合计 28.6 MB， 使 wheel 接近 16 MB，且属于微软版权字体不允许再分发）。中文显示改为运行时自动解析， 详见下文「🅰️ 中文字体」一节。

开发时可用 pip install -e .（或把 src/ 加入 PYTHONPATH）后 import Walimaker。

📚 核心模块详解

🎨 sprite.py - 精灵与动画系统

• EasySpriteStrategy - 静态精灵策略
• ListSpriteStrategy - 帧动画策略
• AnimatorStrategy - 状态动画策略
• SpriteSheet - 精灵表支持
• 支持：旋转、缩放、翻转、颜色修改

📦 resource_manager.py - 资源管理

智能LRU缓存系统：

from Walimaker.resource_manager import ResourceManager
resource_manager = ResourceManager.get_instance()
# 自动缓存管理
image = resource_manager.load_image("image.png")  # 首次加载
cached_image = resource_manager.load_image("image.png")  # 从缓存读取

# 缓存统计
info = resource_manager.get_cache_info()
print(f"图片缓存: {info['images']['current_size']}/{info['images']['maxsize']}")

🎮 API.py - 主要接口

提供简洁的面向对象API：

from Walimaker import *
# 创建各种类型的角色
character = Character("image.png")  # 静态角色
anim_character = Character(["frame1.png", "frame2.png"])  # 动画角色
state_character = Character({  # 状态机角色
    "idle": ["idle_1.png", "idle_2.png"],
    "walk": ["walk_1.png", "walk_2.png", "walk_3.png"]
})

🧭 API文档

📋 概述

Walimaker采用笛卡尔坐标系（像素单位），提供完整的游戏开发功能。坐标原点位于窗口左上角，角度系统：0°指向右侧，逆时针方向角度增加。

🖼️ 窗口设置模块

Character 角色类

构造方法

核心属性

动作方法

交互方法

动画控制

鼠标交互

TextBox 文本框类

构造函数

TextBox(font_size, font=None, bg_color=默认值, font_color=默认值)

font=None 表示自动选择字体（包内 static/ → 系统中文字体 → pygame 默认字体）； 也可以直接给字体路径，例如 TextBox(25, font=r"C:\Windows\Fonts\simhei.ttf")。

属性

方法

事件处理函数

鼠标事件

键盘事件

🚦 高级用法

状态机与动画控制

from Walimaker import *

character = Character({
    "idle": ["idle_1.png", "idle_2.png"],
    "walk": ["walk_1.png", "walk_2.png", "walk_3.png"],
    "jump": ["jump_1.png", "jump_2.png"]
})

# 设置动画参数
character.set_dt("walk", 0.1)  # 走路动画每帧0.1秒
character.set_next_state("walk", "idle")  # 走路结束后回到空闲状态

# 状态切换回调
def on_jump_start():
    print("开始跳跃!")
    
def on_jump_end():
    print("跳跃结束!")
    character.state = "idle"

character.set_start_func("jump", on_jump_start)
character.set_end_func("jump", on_jump_end)

# 切换状态
character.state = "walk"  # 开始走路
character.state = "jump"  # 开始跳跃（触发回调）

资源管理

from Walimaker.config import global_var

# 预加载资源
assets = {
    "images": ["player.png", "enemy.png", "background.png"],
    "fonts": [(None, 24), (None, 36)],          # None = 自动选择中文字体
    "sounds": ["jump.wav", "collect.wav"]
}

global_var.RESOURCE_MANAGER.preload(assets)

# 查看缓存状态
cache_info = global_var.RESOURCE_MANAGER.get_cache_info()
print(f"已缓存图片: {cache_info['images']['current_size']}张")
print(f"已缓存字体: {cache_info['fonts']['current_size']}种")

# 清理缓存
global_var.RESOURCE_MANAGER.clear_cache("image")  # 仅清理图片缓存

🅰️ 中文字体

从 2.3.0 起包内不再携带字体文件（原先的 simkai.ttf + simsun.ttc 合计 28.6 MB， 使 wheel 接近 16 MB，且属于微软授权字体不允许再分发）。TextBox / DialogBox 的字体改为运行时按顺序解析：

• 找不到字体不会报错：只发出一次中文 + 英文的 RuntimeWarning，程序继续运行； 仅当“显式指定的字体文件确实存在但已损坏”时才抛出错误。

• 排查中文显示成方框：

  from Walimaker.fonts import font_info
  print(font_info())
  # {'path': '/System/Library/Fonts/Hiragino Sans GB.ttc', 'source': 'system',
  #  'source_label': '操作系统中文字体', 'has_cjk': True}
  

  若 has_cjk 为 False，说明系统里没有中文字体（常见于精简 Linux / Docker 镜像）， 安装 fonts-noto-cjk（Debian/Ubuntu：apt install fonts-noto-cjk）或设置 WALIMAKER_FONT 指向一个中文字体文件即可。只跑逻辑、不显示画面 （SDL_VIDEODRIVER=dummy）的场景不受影响。

📊 性能优化建议

最佳实践

1. 资源复用：尽量复用Character对象，避免频繁创建销毁
2. 动画优化：使用精灵表和状态机，减少Draw Call
3. 物理优化：将静态物体设为STATIC类型，减少物理计算
4. 内存管理：使用resource_manager的预加载功能
5. 批处理：相似的对象尽量使用相同的材质和大小

常见性能问题

• 问题: 游戏卡顿，FPS下降

• 检查: 使用debug()模式查看物理调试绘制

• 解决: 减少同时活动的物理对象数量

• 问题: 内存占用过高

• 检查: 查看resource_manager缓存状态

• 解决: 调整缓存大小或手动清理缓存

🧪 测试示例

查看 Walimaker/test.py 获取更多完整的游戏示例：

• 平台跳跃游戏
• 弹球物理模拟
• TileMap使用示例
• UI交互演示

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交修改 (git commit -m 'Add some AmazingFeature')
4. 推送分支 (git push origin feature/AmazingFeature)
5. 开启Pull Request

代码规范

• 遵循 PEP 8 编码规范
• 使用 类型注解 (Python 3.7+)
• 注释：重要功能和复杂逻辑需要注释
• 测试：新增功能需包含测试用例

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 支持与反馈

• 文档问题 / Bug 报告：附上重现步骤、错误日志与运行环境（Python、pygame、pymunk 版本）
• 功能建议：欢迎直接反馈
• 版本与更新日志：见 PyPI 项目页 与仓库根目录的 CHANGELOG.md

🙏 致谢

感谢以下开源项目：

• Pygame - 游戏开发库
• Pymunk - 2D物理引擎
• Pytmx - TMX地图解析库

🚀 下一步计划

• WebAssembly支持（让Walimaker在浏览器中运行）
• 3D渲染扩展（基于OpenGL）
• 网络多人游戏支持
• 可视化编辑器开发
• 更多教学资源和示例

🧭 坐标系说明

• 坐标系统：笛卡尔坐标系，原点位于窗口左上角
• 角度系统：0°指向右侧，逆时针方向角度增加
• 颜色值范围：RGB通道 0-255，透明度 0-255
• 音量控制：0.0（静音）到 1.0（最大音量）
• 物理单位：像素为单位，重力默认 900 像素/秒²

教学提示：Walimaker的设计目标是让编程初学者能够在30分钟内制作出第一个可玩的游戏。从简单到复杂，循序渐进地学习游戏开发的核心概念。