Metadata-Version: 2.1
Name: walimaker
Version: 1.0.1
Summary: A Python game engine designed for educational purposes
Home-page: https://github.com/yourusername/walimaker
Author: Walimaker Project
Author-email: Walimaker Project <walimaker@example.com>
Maintainer-email: Walimaker Maintainers <walimaker@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/walimaker
Project-URL: Documentation, https://github.com/yourusername/walimaker#readme
Project-URL: Repository, https://github.com/yourusername/walimaker.git
Project-URL: Issues, https://github.com/yourusername/walimaker/issues
Project-URL: Changelog, https://github.com/yourusername/walimaker/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame>=2.5.0
Requires-Dist: pymunk>=6.5.0
Requires-Dist: pytmx>=3.32
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"

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

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-black.svg)](https://github.com/psf/black)

<p align="center">
  <img src="./Walimaker/static/walimaker-logo.png" alt="Walimaker Logo" width="200"/>
</p>

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

## ✨ 特性亮点

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

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

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

## 🚀 快速开始

### 安装

#### 通过pip安装
```bash
pip install Walimaker
```

### 第一个游戏：移动的角色

```python
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缓存系统**：
```python
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：
```python
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`: 宽度<br>`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`: 目标位置<br>`velocity`: 速度 | - |
| `scale(width, height)` | 缩放尺寸 | `width, height`: 缩放倍数 | - |
| `flipx(enable)` | 水平翻转 | `enable`: 布尔值 | - |
| `flipy(enable)` | 垂直翻转 | `enable`: 布尔值 | - |
| `show()` / `hide()` | 显示/隐藏角色 | - | - |

### 交互方法
| 方法 | 功能 | 参数 | 返回值 |
|------|------|------|--------|
| `play_snd(sound_path, volume)` | 播放音效 | `sound_path`: 音效路径<br>`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`: 状态名<br>`interval`: 间隔时间 | - |
| `set_next_state(from_state, to_state)` | 设置状态切换 | `from_state`: 当前状态<br>`to_state`: 下一状态 | - |
| `set_start_func(state, func)` | 设置开始回调 | `state`: 状态名<br>`func`: 回调函数 | - |
| `set_end_func(state, func)` | 设置结束回调 | `state`: 状态名<br>`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` |

---

## 🚦 高级用法

### 状态机与动画控制
```python
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"  # 开始跳跃（触发回调）
```

### 资源管理
```python
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](LICENSE) 文件了解详情。

## 📞 支持与反馈

- **文档问题**：请在GitHub提交Issue
- **功能建议**：使用[GitHub Discussions](https://github.com/yourusername/walimaker/discussions)
- **Bug报告**：提供重现步骤和错误日志

## 🙏 致谢

感谢以下开源项目：
- [Pygame](https://www.pygame.org/) - 游戏开发库
- [Pymunk](https://www.pymunk.org/) - 2D物理引擎
- [Pytmx](https://github.com/pytmx/pytmx) - TMX地图解析库

## 🚀 下一步计划

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

---

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

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

