walimaker 1.0.1

A Python game engine designed for educational purposes

🎮 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:
    # 事件处理
    if key_pressed("w"):
        character.forward(5)
    if key_pressed("a"):
        character.left(5)
    if key_pressed("d"):
        character.right(5)
    
    # 动画播放
    character.play_anim()
    
    # 渲染更新
    update()

📁 项目结构

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          # 示例和测试代码
└── 📁 static/          # 资源文件
    ├── 🖼️ *.png        # 图片资源
    └── 🅰️ *.ttf        # 字体文件

📚 核心模块详解

🎨 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°指向右侧，逆时针方向角度增加。

---

🖼️ 窗口设置模块

函数名	功能描述	参数说明	返回值	备注
setup(width, height)	创建指定尺寸的窗口	width: 宽度 height: 高度	-	窗口在屏幕中心生成
update()	刷新画面显示	-	-	将修改内容更新到窗口
title(text)	设置窗口标题	text: 标题文本	-	-
bgpic(image_path)	设置背景图片	image_path: 图片路径	-	图片小于窗口时显示黑色背景
bgmusic(music_path)	播放背景音乐	music_path: 音乐路径	-	循环播放模式
set_volume(level)	设置音量	level: 0-1浮点数	-	全局音量控制
tracer(enable)	自动刷新控制	enable: 布尔值	-	防止主线程卡顿
save_screen(path)	截图保存	path: 保存路径	-	保存当前窗口画面
set_mouse_visible(visible)	鼠标显示控制	visible: 布尔值	-	显示/隐藏鼠标光标

---

Character 角色类

构造方法

方式	描述	参数	返回值
单图模式	创建静态角色	image_path: 图片路径	Character对象
动画序列	创建帧动画角色	image_list: 图片路径列表	Character对象
状态动画	创建多状态角色	anim_dict: {状态名: 图片列表}	Character对象

核心属性

属性	类型	描述	权限
x, y	float	角色坐标位置	读写
pos	tuple	坐标元组 (x, y)	读写
rot	float	旋转角度 (0°=右侧，逆时针)	读写
dir	vec	方向向量	读写
red, green, blue, alpha	int	颜色通道值 (0-255)	读写
color	tuple	颜色元组 (r, g, b, a)	读写
visible	bool	可见性状态	只读
width, height	int	图片尺寸	只读
frame	int	当前动画帧索引	读写
state	str	当前动画状态名	读写
dt	float	动画帧间隔时间	读写
layer	int	渲染层级 (0=底层)	读写

动作方法

方法	功能	参数	返回值
forward(distance)	向前移动	distance: 像素距离	-
backward(distance)	向后移动	distance: 像素距离	-
left(angle)	左转	angle: 旋转角度	-
right(angle)	右转	angle: 旋转角度	-
goto(x, y)	瞬移到坐标	x, y: 目标坐标	-
slide_to(pos, velocity)	滑动移动	pos: 目标位置 velocity: 速度	-
scale(width, height)	缩放尺寸	width, height: 缩放倍数	-
flipx(enable)	水平翻转	enable: 布尔值	-
flipy(enable)	垂直翻转	enable: 布尔值	-
show() / hide()	显示/隐藏角色	-	-

交互方法

方法	功能	参数	返回值
play_snd(sound_path, volume)	播放音效	sound_path: 音效路径 volume: 音量(0-1)	-
collide(target)	碰撞检测	target: 角色或坐标	bool
separate(target)	分离检测	target: 角色或坐标	bool
distance(target)	距离计算	target: 角色或坐标	float
say(text)	显示对话气泡	text: 对话内容	-

动画控制

方法	功能	参数	返回值
play_anim()	开始播放动画	-	-
stop_anim()	停止播放动画	-	-
set_dt(state, interval)	设置帧间隔	state: 状态名 interval: 间隔时间	-
set_next_state(from_state, to_state)	设置状态切换	from_state: 当前状态 to_state: 下一状态	-
set_start_func(state, func)	设置开始回调	state: 状态名 func: 回调函数	-
set_end_func(state, func)	设置结束回调	state: 状态名 func: 回调函数	-

鼠标交互

方法	功能	参数	返回值
get_mouse_clicked()	鼠标点击检测	-	bool
get_mouse_just_clicked()	鼠标点击瞬间检测	-	bool
get_mouse_just_released()	鼠标释放瞬间检测	-	bool
get_mouse_upon()	鼠标悬停检测	-	bool
kill()	销毁角色对象	-	-

---

TextBox 文本框类

构造函数

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

属性

属性	类型	描述	权限
pos	tuple	文本框位置坐标	读写
color	tuple	文本颜色 (r, g, b)	读写

方法

方法	功能	参数	返回值
print(content)	显示文本内容	content: 文本字符串	-
goto(x, y)	移动文本框	x, y: 目标坐标	-

---

事件处理函数

鼠标事件

函数	功能	参数	返回值
get_mouse_pos()	获取鼠标坐标	-	tuple (x, y)
get_mouse_rel()	获取鼠标移动向量	-	tuple (dx, dy)
get_mouse_clicked()	检测鼠标按下状态	-	bool
get_mouse_just_clicked()	检测鼠标按下瞬间	-	bool
get_mouse_just_released()	检测鼠标释放瞬间	-	bool

键盘事件

函数	功能	参数	返回值
key_pressed(key)	检测按键按下状态	key: 按键常量(可选)	bool
key_just_pressed(key)	检测按键按下瞬间	key: 按键常量(可选)	bool
key_just_released(key)	检测按键释放瞬间	key: 按键常量(可选)	bool
key_input()	获取按键输入字符	-	str

---

🚦 高级用法

状态机与动画控制

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": [("static/simkai.ttf", 24), ("static/simkai.ttf", 36)],
    "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")  # 仅清理图片缓存

📊 性能优化建议

最佳实践

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 文件了解详情。

📞 支持与反馈

• 文档问题：请在GitHub提交Issue
• 功能建议：使用GitHub Discussions
• Bug报告：提供重现步骤和错误日志

🙏 致谢

感谢以下开源项目：

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

🚀 下一步计划

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

---

🧭 坐标系说明

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

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