walimaker 4.0.2__tar.gz → 4.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {walimaker-4.0.2 → walimaker-4.2.0}/CHANGELOG.md +42 -0
- {walimaker-4.0.2/src/walimaker.egg-info → walimaker-4.2.0}/PKG-INFO +103 -15
- {walimaker-4.0.2 → walimaker-4.2.0}/README.md +99 -13
- {walimaker-4.0.2 → walimaker-4.2.0}/pyproject.toml +8 -1
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/API.py +2 -1
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/_version.py +1 -1
- walimaker-4.2.0/src/Walimaker/build.py +550 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/config.py +3 -0
- walimaker-4.2.0/src/Walimaker/error_help.py +851 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/resource_manager.py +6 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/screen.py +66 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/tiledmap.py +18 -2
- {walimaker-4.0.2 → walimaker-4.2.0/src/walimaker.egg-info}/PKG-INFO +103 -15
- {walimaker-4.0.2 → walimaker-4.2.0}/src/walimaker.egg-info/SOURCES.txt +1 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/walimaker.egg-info/dependency_links.txt +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/walimaker.egg-info/entry_points.txt +1 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/walimaker.egg-info/requires.txt +4 -1
- {walimaker-4.0.2 → walimaker-4.2.0}/src/walimaker.egg-info/top_level.txt +0 -0
- walimaker-4.0.2/src/Walimaker/error_help.py +0 -429
- {walimaker-4.0.2 → walimaker-4.2.0}/LICENSE +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/MANIFEST.in +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/examples/README.md +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/examples/assets/level.tmx +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/examples/assets/tiles.png +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/examples/physics_basics.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/examples/physics_constraints.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/examples/tiledmap_basics.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/setup.cfg +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/__init__.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/animation.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/camera.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/collision.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/constraints.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/cursor.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/draw.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/draw_options.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/events.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/facilitate.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/fonts.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/input.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/lru_cache.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/music.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/objects.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/physics.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/py.typed +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/settings.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/sprite.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/static/DialogBox.png +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/static/pymunk_logo_googlecode.png +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/static/walimaker-logo.png +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/test.py +0 -0
- {walimaker-4.0.2 → walimaker-4.2.0}/src/Walimaker/textbox.py +0 -0
|
@@ -2,6 +2,48 @@
|
|
|
2
2
|
|
|
3
3
|
本项目遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
4
4
|
|
|
5
|
+
## [4.2.0] - 2026-11-19
|
|
6
|
+
|
|
7
|
+
### 新增
|
|
8
|
+
|
|
9
|
+
- **HTML5 打包(`walimaker build --web`)**:把作品打包成可分享的网页游戏,学生无需让同学安装 Python。
|
|
10
|
+
- 新增 `src/Walimaker/build.py` 与 `walimaker` 命令;依赖 pygbag(Python 3.13 运行时 + pygame-ce + pymunk 6.4.0 wasm)。
|
|
11
|
+
- 自动完成:入口脚本检查、资源收集、内置 Walimaker 源码、pytmx 按需内置、调用 pygbag、生成
|
|
12
|
+
`dist/web/` 与 `dist/<名字>-web.zip`(`index.html` 位于 zip 根,可直接上传 itch.io)。
|
|
13
|
+
- 拦截网页不支持/会卡死的写法:顶层 `while True`、`threading` / `multiprocessing` /
|
|
14
|
+
`subprocess` / `tkinter`;提示 `input()`、`sleep()`、`os.chdir()`、WAV/MP3 转 OGG、中文字体显式指定。
|
|
15
|
+
- **统一主循环 `run(loop, world=None)`**:每帧执行 `loop()` 后自动 `update()`;桌面端同步循环,
|
|
16
|
+
网页端(`sys.platform == "emscripten"`)自动 `await asyncio.sleep(0)`,避免浏览器卡死。
|
|
17
|
+
推荐所有新作品使用,桌面/网页共用一套代码。
|
|
18
|
+
- **网页兼容处理**:
|
|
19
|
+
- `World.RUNNING` + 关窗处理:网页端收到 `QUIT` 时不再调用 `os._exit`,改为结束 `run()` 循环;
|
|
20
|
+
`done()` 在网页端改为空转的 `run()`,避免页面冻结。
|
|
21
|
+
- `ResourceManager` 在 Emscripten 下跳过 `os.dup()/dup2()` 的 stderr 重定向(网页没有真实 fd)。
|
|
22
|
+
- `pytmx` 改为可选导入:不用 TileMap 的作品不再因为缺少 pytmx 而无法导入;用到时给出明确中文提示。
|
|
23
|
+
- 最低 pymunk 版本下调到 **6.4.0**(与网页版 wasm 轮子一致,桌面全部测试已通过),
|
|
24
|
+
`scripts/check.py --matrix` 增加 6.4.0 一档。
|
|
25
|
+
- 新增 `tests/run_test.py`(6 项)与 `tests/build_test.py`(5 项),覆盖主循环、网页分支、
|
|
26
|
+
stderr 保护、打包工程准备、资源提示与 zip 产物。
|
|
27
|
+
|
|
28
|
+
## [4.1.0] - 2026-11-18
|
|
29
|
+
|
|
30
|
+
### 改进
|
|
31
|
+
|
|
32
|
+
- **中文报错助手:补齐报错类型检测,提示文案改为一句话**(`Walimaker.error_help`):
|
|
33
|
+
- 规则从 17 条扩到 **49 条**。新增:导入名不存在(`ImportError`)、局部变量未赋值、通用属性错误、
|
|
34
|
+
模块属性错误、参数名 / 参数个数错误、类型混用、在 `None` 上取下标或调用、不可下标、不可遍历、
|
|
35
|
+
小数当整数、索引越界、字典缺键、数字转换失败、解包个数不对、数学定义域、JSON 格式错误、
|
|
36
|
+
权限不足、路径是文件夹、通用 `OSError`、文本编码错误、图片格式不支持、矩形参数错误、
|
|
37
|
+
无显示设备、窗口已关闭、内存不足、数值溢出、`assert` 失败、`StopIteration`、`EOFError` 等。
|
|
38
|
+
- **检测更准**:pygame 按键常量改用 pygame 真实常量表判断(不再按 `APP` / `KEY` / `TEXT`
|
|
39
|
+
这类宽前缀猜,修掉把 `APPLE` 误判成常量的问题);图片类型的 `KeyError` 与普通缺键区分;
|
|
40
|
+
模块属性错误不再硬编码成 pygame;文件路径不再被 `rsplit(":")` 截断 Windows 盘符;
|
|
41
|
+
`TabError` 不再重复命中缩进错误;框架双语报错不再重复解释。
|
|
42
|
+
- **文案更简约**:每条提示只保留「标题 + 一句原因 + 一句解决」,去掉冗长背景与默认「参考」行;
|
|
43
|
+
同一条异常只取第一条命中规则(规则按"具体 → 宽泛"排序),不再堆叠多条提示。
|
|
44
|
+
- 字段缺失或格式化失败时用 `?` 兜底,不影响原始报错。
|
|
45
|
+
- `tests/error_help_test.py` 扩充到 **48 项检查**:新增 26 个异常样例、检测准确性与"单条提示 ≤ 5 行"的简约性断言。
|
|
46
|
+
|
|
5
47
|
## [4.0.2] - 2026-09-18
|
|
6
48
|
|
|
7
49
|
### 修复
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: walimaker
|
|
3
|
-
Version: 4.0
|
|
3
|
+
Version: 4.2.0
|
|
4
4
|
Summary: A Python game engine designed for educational purposes
|
|
5
5
|
Author-email: Walimaker Project <walimaker@example.com>
|
|
6
6
|
Maintainer-email: Walimaker Maintainers <walimaker@example.com>
|
|
@@ -27,7 +27,7 @@ Requires-Python: >=3.8.1
|
|
|
27
27
|
Description-Content-Type: text/markdown
|
|
28
28
|
License-File: LICENSE
|
|
29
29
|
Requires-Dist: pygame>=2.5.0
|
|
30
|
-
Requires-Dist: pymunk>=6.
|
|
30
|
+
Requires-Dist: pymunk>=6.4.0
|
|
31
31
|
Requires-Dist: pytmx>=3.32
|
|
32
32
|
Provides-Extra: dev
|
|
33
33
|
Requires-Dist: black>=23.0; extra == "dev"
|
|
@@ -38,6 +38,8 @@ Requires-Dist: twine>=4.0; extra == "dev"
|
|
|
38
38
|
Provides-Extra: docs
|
|
39
39
|
Requires-Dist: mkdocs>=1.4; extra == "docs"
|
|
40
40
|
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
|
|
41
|
+
Provides-Extra: web
|
|
42
|
+
Requires-Dist: pygbag>=0.9.3; extra == "web"
|
|
41
43
|
Dynamic: license-file
|
|
42
44
|
|
|
43
45
|
# 🎮 Walimaker - 专为教学设计的Python游戏引擎
|
|
@@ -54,7 +56,7 @@ Dynamic: license-file
|
|
|
54
56
|
|
|
55
57
|
## 📖 目录
|
|
56
58
|
|
|
57
|
-
- [✨ 特性亮点](#features)|[🚀 快速开始](#quickstart)|[🧭 中文报错提示](#error-help)
|
|
59
|
+
- [✨ 特性亮点](#features)|[🚀 快速开始](#quickstart)|[📦 打包与分享](#packaging)|[🧭 中文报错提示](#error-help)
|
|
58
60
|
- [📁 项目结构](#structure)|[🧰 本地开发与测试](#dev-test)
|
|
59
61
|
- [📖 API 参考](#api):窗口与主循环、Character/对象模型、物理引擎、约束、相机、TileMap、Sprite、TextBox、输入、音频、资源、报错助手、字体、世界与全局状态、场景级工具
|
|
60
62
|
- [🚦 高级用法](#advanced):多世界、相机手感、防隧穿、约束、TileMap、动画状态机、资源管理、中文字体
|
|
@@ -82,7 +84,8 @@ Dynamic: license-file
|
|
|
82
84
|
### 🚀 开发效率
|
|
83
85
|
- **调试工具**:调试绘制 `debug()`、自动刷新 `tracer()`、移动限速 `speed()`、性能基准脚本
|
|
84
86
|
- **类型友好**:随包提供 `py.typed`,编辑器与 mypy 能直接提示参数类型
|
|
85
|
-
-
|
|
87
|
+
- **作品分享**:`walimaker build game.py --web` 一条命令打包成网页游戏(pygbag / WebAssembly)
|
|
88
|
+
- **测试与门禁**:17 个测试文件 + `scripts/check.py`(一条命令跑 black / flake8 / mypy / 全部测试,
|
|
86
89
|
并支持 `--matrix` 自动跑 pymunk 6/7 双版本);其中 `tests/behaviour_snapshot_test.py` 用固定
|
|
87
90
|
假时钟把整套对象/物理/渲染行为压成 27 项观测与基线对拍,重构时"行为有没有变"一眼可见
|
|
88
91
|
- **模块化设计**:对象模型、精灵动画、物理、渲染、资源各司其职,便于定制
|
|
@@ -134,6 +137,85 @@ while True:
|
|
|
134
137
|
update()
|
|
135
138
|
```
|
|
136
139
|
|
|
140
|
+
> 准备把作品打包成网页版时,请把主循环改成 `run(game)`(见下面 [📦 打包与分享](#packaging));
|
|
141
|
+
> 桌面端也支持这种写法,不需要维护两套代码。
|
|
142
|
+
|
|
143
|
+
<a id="packaging"></a>
|
|
144
|
+
|
|
145
|
+
## 📦 打包与分享(HTML5)
|
|
146
|
+
|
|
147
|
+
作品做完后,可以一条命令打包成网页游戏,把链接发给任何人玩(对方无需安装 Python)。
|
|
148
|
+
|
|
149
|
+
### 1. 把主循环改成 `run(game)`
|
|
150
|
+
|
|
151
|
+
网页版不能出现顶层 `while True`(会卡死浏览器),请改成:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
from Walimaker import *
|
|
155
|
+
|
|
156
|
+
setup(800, 600)
|
|
157
|
+
hero = Character("hero.png", size=(32, 32))
|
|
158
|
+
set_gravity(0, -1200)
|
|
159
|
+
|
|
160
|
+
def game():
|
|
161
|
+
if key_pressed(K_RIGHT):
|
|
162
|
+
hero.forward(5)
|
|
163
|
+
# 不要写 while True,也不要自己调用 update()
|
|
164
|
+
|
|
165
|
+
run(game)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
桌面端 `run(game)` 同样可用,因此不需要维护两套代码。
|
|
169
|
+
|
|
170
|
+
### 2. 安装打包工具
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
pip install "walimaker[web]"
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### 3. 打包
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
walimaker build game.py --web
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
产物:
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
dist/
|
|
186
|
+
├── web/ # 静态网站:index.html + wasm + 你的资源
|
|
187
|
+
└── game-web.zip # 直接上传到 itch.io / GitHub Pages / Netlify
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
本地预览(不要直接双击 `index.html`,浏览器会拦截 wasm):
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
cd dist/web
|
|
194
|
+
python -m http.server 8000
|
|
195
|
+
# 打开 http://localhost:8000
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
分享方式:
|
|
199
|
+
|
|
200
|
+
- **itch.io**:上传 `game-web.zip`,项目类型选 HTML5,入口为 `index.html`
|
|
201
|
+
- **GitHub Pages**:把 `dist/web/` 推到 `gh-pages` 分支
|
|
202
|
+
- **Netlify Drop**:把 `dist/web/` 目录拖进去即可
|
|
203
|
+
|
|
204
|
+
### 网页版限制
|
|
205
|
+
|
|
206
|
+
| 限制 | 说明 |
|
|
207
|
+
|---|---|
|
|
208
|
+
| 主循环 | 必须写成 `run(game)`;不能用顶层 `while True` |
|
|
209
|
+
| 物理 | pygbag 3.13 提供 **pymunk 6.4.0**(桌面端最低也支持 6.4.0,全部测试通过) |
|
|
210
|
+
| 音频 | 推荐 `.ogg`;`.wav` / `.mp3` 打包时会提示先转码 |
|
|
211
|
+
| 中文字体 | 浏览器没有系统中文字体,请显式 `TextBox(font="assets/你的字体.ttf")` |
|
|
212
|
+
| 标准库 | 不能用 `threading` / `multiprocessing` / `subprocess` / `tkinter` / `input()` |
|
|
213
|
+
| 文件写入 | 浏览器虚拟文件系统里的写入不会保存到用户电脑 |
|
|
214
|
+
|
|
215
|
+
> 首次打开网页需要从 pygbag 官方 CDN 下载 Python/WASM 运行时(约 10–20 MB),之后会走浏览器缓存。
|
|
216
|
+
> 如果页面一直停在 `Loading`,通常是 `pygame-web.github.io` 较慢或不可达:换网络重试,
|
|
217
|
+
> 或用 `walimaker build game.py --web --cdn <你的镜像地址>` 指定自建/镜像 CDN。
|
|
218
|
+
|
|
137
219
|
<a id="error-help"></a>
|
|
138
220
|
|
|
139
221
|
## 🧭 中文报错提示(教学特性)
|
|
@@ -149,16 +231,19 @@ NameError: name 'K_SPACE' is not defined
|
|
|
149
231
|
|
|
150
232
|
────────────────────────────────────────────────────────────────
|
|
151
233
|
【Walimaker 中文提示】按键/事件常量「K_SPACE」没有导入
|
|
152
|
-
原因:
|
|
153
|
-
|
|
154
|
-
一起提供;② 或者显式写 from pygame.locals import *。
|
|
155
|
-
参考:CHANGELOG 2.1.0「恢复 pygame 事件/按键常量的导出」
|
|
234
|
+
原因:K_SPACE、KEYDOWN 这些常量要先导入才能用。
|
|
235
|
+
解决:升级 walimaker(pip install -U walimaker),或写 from pygame.locals import *。
|
|
156
236
|
────────────────────────────────────────────────────────────────
|
|
157
237
|
```
|
|
158
238
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
239
|
+
提示保持精简:每条错误只给「标题 + 一句原因 + 一句解决」,不再罗列背景知识;
|
|
240
|
+
框架自己抛出的双语报错已经说清楚了,不会重复追加。
|
|
241
|
+
|
|
242
|
+
覆盖的常见错误包括:缺少依赖、名字未定义(按键常量有专项提示)、忘记调用 `setup()`、
|
|
243
|
+
文件找不到 / 没有权限 / 路径是文件夹、图片音频格式与文本编码问题、pymunk 坐标类型与版本兼容问题、
|
|
244
|
+
`key_pressed("w")` 传了字符串、图片类型不支持、`setup()` 参数不对、索引越界、字典缺键、
|
|
245
|
+
数字转换 / 解包错误、类型混用、不可下标 / 不可遍历、参数名或个数错误、Tab 与空格混用、语法 / 缩进错误、
|
|
246
|
+
除零、递归过深、内存不足、没有显示设备、窗口已关闭、矩形参数错误等;
|
|
162
247
|
如果报错发生在 Walimaker 自身代码里,会提示"可能是框架问题 + 如何反馈"。
|
|
163
248
|
|
|
164
249
|
**关闭方式**(默认开启):
|
|
@@ -206,6 +291,7 @@ Walimaker/
|
|
|
206
291
|
├── 📄 API.py # 主要API接口(Character、窗口管理等)
|
|
207
292
|
├── 📄 sprite.py # 精灵和动画系统
|
|
208
293
|
├── ⚙️ physics.py # 物理引擎封装(基于Pymunk)
|
|
294
|
+
├── 📦 build.py # HTML5 打包命令(walimaker build --web)
|
|
209
295
|
├── 📷 camera.py # 相机系统(缩放、跟随)
|
|
210
296
|
├── 🗺️ tiledmap.py # TileMap地图系统
|
|
211
297
|
├── 📝 textbox.py # UI文本组件
|
|
@@ -233,7 +319,7 @@ Walimaker/
|
|
|
233
319
|
```bash
|
|
234
320
|
uv sync # 创建 .venv(Python 版本由 .python-version 指定)并安装依赖
|
|
235
321
|
uv run python scripts/check.py # 静态检查 + 全部测试(等价于 CI)
|
|
236
|
-
uv run python scripts/check.py --matrix # 额外跑 pymunk 6.11.1 /
|
|
322
|
+
uv run python scripts/check.py --matrix # 额外跑 pymunk 6.4.0 / 6.11.1 / 最新版矩阵
|
|
237
323
|
uv run python tests/smoke_test.py # 也可以只跑单个测试
|
|
238
324
|
uv run python tests/behaviour_snapshot_test.py # 27 项行为快照对拍(重构后"行为有没有变")
|
|
239
325
|
WALIMAKER_UPDATE_BASELINE=1 uv run python tests/behaviour_snapshot_test.py # 有意改动时重生成基线
|
|
@@ -242,7 +328,7 @@ uv run python benchmarks/perf_baseline.py
|
|
|
242
328
|
|
|
243
329
|
- `uv.lock` 随仓库提供(133 个包,按 Python 3.8.1+ 全范围解析),`uv sync` 按锁文件精确安装;
|
|
244
330
|
升级依赖用 `uv lock --upgrade`。
|
|
245
|
-
- `--matrix` 用 `uv run --no-project --with pymunk==
|
|
331
|
+
- `--matrix` 用 `uv run --no-project --with pymunk==X` 现开临时环境,三个版本各跑一遍全部测试,
|
|
246
332
|
**不需要手动准备两个 venv**、也不会污染当前环境(整轮约 15 秒)。
|
|
247
333
|
- 不想用 uv 也可以:`pip install -e ".[dev]"` 后 `python scripts/check.py`,效果相同。
|
|
248
334
|
|
|
@@ -319,7 +405,8 @@ sign(n) # n 的符号:1 / -1 / 0
|
|
|
319
405
|
|------|------|------|--------|
|
|
320
406
|
| `setup(width, height, world=None)` | 初始化一个世界:窗口、相机、精灵组、物理空间 | 宽、高(整数像素) | `Screen` |
|
|
321
407
|
| `update(world=None)` | 推进一帧(物理 → 逻辑 → 渲染) | - | - |
|
|
322
|
-
| `
|
|
408
|
+
| `run(loop, world=None)` | 推荐主循环:每帧执行 `loop()` 后自动 `update()`;网页版自动让出浏览器事件循环 | 每帧函数 | - |
|
|
409
|
+
| `done(world=None)` | 进入死循环,直到关窗(网页端改为空转的 `run()`) | - | - |
|
|
323
410
|
| `title(text)` | 设置窗口标题 | 文本 | - |
|
|
324
411
|
| `save_screen(path, world=None)` | 把下一帧画面保存为图片 | 路径 | - |
|
|
325
412
|
| `init()` | 初始化 pygame / mixer / font(幂等,一般由 `setup()` 调用) | - | - |
|
|
@@ -1054,7 +1141,8 @@ uv run python examples/tiledmap_basics.py # TMX 地图当背景 + 对象
|
|
|
1054
1141
|
- [ ] 插件 / 组件系统
|
|
1055
1142
|
- [ ] 常用 UI 控件(按钮、输入框、列表…)
|
|
1056
1143
|
- [ ] 触控 / 移动端手势
|
|
1057
|
-
- [
|
|
1144
|
+
- [x] **HTML5 打包(实验性)**:`walimaker build game.py --web`(pygbag + WebAssembly + pymunk 6.4.0)
|
|
1145
|
+
- 后续:自建运行时镜像(减少对 pygbag CDN 的依赖)、桌面端一键打包(PyInstaller)
|
|
1058
1146
|
- [ ] 3D 渲染扩展(基于 OpenGL)
|
|
1059
1147
|
- [ ] 网络多人游戏支持
|
|
1060
1148
|
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
|
|
13
13
|
## 📖 目录
|
|
14
14
|
|
|
15
|
-
- [✨ 特性亮点](#features)|[🚀 快速开始](#quickstart)|[🧭 中文报错提示](#error-help)
|
|
15
|
+
- [✨ 特性亮点](#features)|[🚀 快速开始](#quickstart)|[📦 打包与分享](#packaging)|[🧭 中文报错提示](#error-help)
|
|
16
16
|
- [📁 项目结构](#structure)|[🧰 本地开发与测试](#dev-test)
|
|
17
17
|
- [📖 API 参考](#api):窗口与主循环、Character/对象模型、物理引擎、约束、相机、TileMap、Sprite、TextBox、输入、音频、资源、报错助手、字体、世界与全局状态、场景级工具
|
|
18
18
|
- [🚦 高级用法](#advanced):多世界、相机手感、防隧穿、约束、TileMap、动画状态机、资源管理、中文字体
|
|
@@ -40,7 +40,8 @@
|
|
|
40
40
|
### 🚀 开发效率
|
|
41
41
|
- **调试工具**:调试绘制 `debug()`、自动刷新 `tracer()`、移动限速 `speed()`、性能基准脚本
|
|
42
42
|
- **类型友好**:随包提供 `py.typed`,编辑器与 mypy 能直接提示参数类型
|
|
43
|
-
-
|
|
43
|
+
- **作品分享**:`walimaker build game.py --web` 一条命令打包成网页游戏(pygbag / WebAssembly)
|
|
44
|
+
- **测试与门禁**:17 个测试文件 + `scripts/check.py`(一条命令跑 black / flake8 / mypy / 全部测试,
|
|
44
45
|
并支持 `--matrix` 自动跑 pymunk 6/7 双版本);其中 `tests/behaviour_snapshot_test.py` 用固定
|
|
45
46
|
假时钟把整套对象/物理/渲染行为压成 27 项观测与基线对拍,重构时"行为有没有变"一眼可见
|
|
46
47
|
- **模块化设计**:对象模型、精灵动画、物理、渲染、资源各司其职,便于定制
|
|
@@ -92,6 +93,85 @@ while True:
|
|
|
92
93
|
update()
|
|
93
94
|
```
|
|
94
95
|
|
|
96
|
+
> 准备把作品打包成网页版时,请把主循环改成 `run(game)`(见下面 [📦 打包与分享](#packaging));
|
|
97
|
+
> 桌面端也支持这种写法,不需要维护两套代码。
|
|
98
|
+
|
|
99
|
+
<a id="packaging"></a>
|
|
100
|
+
|
|
101
|
+
## 📦 打包与分享(HTML5)
|
|
102
|
+
|
|
103
|
+
作品做完后,可以一条命令打包成网页游戏,把链接发给任何人玩(对方无需安装 Python)。
|
|
104
|
+
|
|
105
|
+
### 1. 把主循环改成 `run(game)`
|
|
106
|
+
|
|
107
|
+
网页版不能出现顶层 `while True`(会卡死浏览器),请改成:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from Walimaker import *
|
|
111
|
+
|
|
112
|
+
setup(800, 600)
|
|
113
|
+
hero = Character("hero.png", size=(32, 32))
|
|
114
|
+
set_gravity(0, -1200)
|
|
115
|
+
|
|
116
|
+
def game():
|
|
117
|
+
if key_pressed(K_RIGHT):
|
|
118
|
+
hero.forward(5)
|
|
119
|
+
# 不要写 while True,也不要自己调用 update()
|
|
120
|
+
|
|
121
|
+
run(game)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
桌面端 `run(game)` 同样可用,因此不需要维护两套代码。
|
|
125
|
+
|
|
126
|
+
### 2. 安装打包工具
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
pip install "walimaker[web]"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### 3. 打包
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
walimaker build game.py --web
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
产物:
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
dist/
|
|
142
|
+
├── web/ # 静态网站:index.html + wasm + 你的资源
|
|
143
|
+
└── game-web.zip # 直接上传到 itch.io / GitHub Pages / Netlify
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
本地预览(不要直接双击 `index.html`,浏览器会拦截 wasm):
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
cd dist/web
|
|
150
|
+
python -m http.server 8000
|
|
151
|
+
# 打开 http://localhost:8000
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
分享方式:
|
|
155
|
+
|
|
156
|
+
- **itch.io**:上传 `game-web.zip`,项目类型选 HTML5,入口为 `index.html`
|
|
157
|
+
- **GitHub Pages**:把 `dist/web/` 推到 `gh-pages` 分支
|
|
158
|
+
- **Netlify Drop**:把 `dist/web/` 目录拖进去即可
|
|
159
|
+
|
|
160
|
+
### 网页版限制
|
|
161
|
+
|
|
162
|
+
| 限制 | 说明 |
|
|
163
|
+
|---|---|
|
|
164
|
+
| 主循环 | 必须写成 `run(game)`;不能用顶层 `while True` |
|
|
165
|
+
| 物理 | pygbag 3.13 提供 **pymunk 6.4.0**(桌面端最低也支持 6.4.0,全部测试通过) |
|
|
166
|
+
| 音频 | 推荐 `.ogg`;`.wav` / `.mp3` 打包时会提示先转码 |
|
|
167
|
+
| 中文字体 | 浏览器没有系统中文字体,请显式 `TextBox(font="assets/你的字体.ttf")` |
|
|
168
|
+
| 标准库 | 不能用 `threading` / `multiprocessing` / `subprocess` / `tkinter` / `input()` |
|
|
169
|
+
| 文件写入 | 浏览器虚拟文件系统里的写入不会保存到用户电脑 |
|
|
170
|
+
|
|
171
|
+
> 首次打开网页需要从 pygbag 官方 CDN 下载 Python/WASM 运行时(约 10–20 MB),之后会走浏览器缓存。
|
|
172
|
+
> 如果页面一直停在 `Loading`,通常是 `pygame-web.github.io` 较慢或不可达:换网络重试,
|
|
173
|
+
> 或用 `walimaker build game.py --web --cdn <你的镜像地址>` 指定自建/镜像 CDN。
|
|
174
|
+
|
|
95
175
|
<a id="error-help"></a>
|
|
96
176
|
|
|
97
177
|
## 🧭 中文报错提示(教学特性)
|
|
@@ -107,16 +187,19 @@ NameError: name 'K_SPACE' is not defined
|
|
|
107
187
|
|
|
108
188
|
────────────────────────────────────────────────────────────────
|
|
109
189
|
【Walimaker 中文提示】按键/事件常量「K_SPACE」没有导入
|
|
110
|
-
原因:
|
|
111
|
-
|
|
112
|
-
一起提供;② 或者显式写 from pygame.locals import *。
|
|
113
|
-
参考:CHANGELOG 2.1.0「恢复 pygame 事件/按键常量的导出」
|
|
190
|
+
原因:K_SPACE、KEYDOWN 这些常量要先导入才能用。
|
|
191
|
+
解决:升级 walimaker(pip install -U walimaker),或写 from pygame.locals import *。
|
|
114
192
|
────────────────────────────────────────────────────────────────
|
|
115
193
|
```
|
|
116
194
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
195
|
+
提示保持精简:每条错误只给「标题 + 一句原因 + 一句解决」,不再罗列背景知识;
|
|
196
|
+
框架自己抛出的双语报错已经说清楚了,不会重复追加。
|
|
197
|
+
|
|
198
|
+
覆盖的常见错误包括:缺少依赖、名字未定义(按键常量有专项提示)、忘记调用 `setup()`、
|
|
199
|
+
文件找不到 / 没有权限 / 路径是文件夹、图片音频格式与文本编码问题、pymunk 坐标类型与版本兼容问题、
|
|
200
|
+
`key_pressed("w")` 传了字符串、图片类型不支持、`setup()` 参数不对、索引越界、字典缺键、
|
|
201
|
+
数字转换 / 解包错误、类型混用、不可下标 / 不可遍历、参数名或个数错误、Tab 与空格混用、语法 / 缩进错误、
|
|
202
|
+
除零、递归过深、内存不足、没有显示设备、窗口已关闭、矩形参数错误等;
|
|
120
203
|
如果报错发生在 Walimaker 自身代码里,会提示"可能是框架问题 + 如何反馈"。
|
|
121
204
|
|
|
122
205
|
**关闭方式**(默认开启):
|
|
@@ -164,6 +247,7 @@ Walimaker/
|
|
|
164
247
|
├── 📄 API.py # 主要API接口(Character、窗口管理等)
|
|
165
248
|
├── 📄 sprite.py # 精灵和动画系统
|
|
166
249
|
├── ⚙️ physics.py # 物理引擎封装(基于Pymunk)
|
|
250
|
+
├── 📦 build.py # HTML5 打包命令(walimaker build --web)
|
|
167
251
|
├── 📷 camera.py # 相机系统(缩放、跟随)
|
|
168
252
|
├── 🗺️ tiledmap.py # TileMap地图系统
|
|
169
253
|
├── 📝 textbox.py # UI文本组件
|
|
@@ -191,7 +275,7 @@ Walimaker/
|
|
|
191
275
|
```bash
|
|
192
276
|
uv sync # 创建 .venv(Python 版本由 .python-version 指定)并安装依赖
|
|
193
277
|
uv run python scripts/check.py # 静态检查 + 全部测试(等价于 CI)
|
|
194
|
-
uv run python scripts/check.py --matrix # 额外跑 pymunk 6.11.1 /
|
|
278
|
+
uv run python scripts/check.py --matrix # 额外跑 pymunk 6.4.0 / 6.11.1 / 最新版矩阵
|
|
195
279
|
uv run python tests/smoke_test.py # 也可以只跑单个测试
|
|
196
280
|
uv run python tests/behaviour_snapshot_test.py # 27 项行为快照对拍(重构后"行为有没有变")
|
|
197
281
|
WALIMAKER_UPDATE_BASELINE=1 uv run python tests/behaviour_snapshot_test.py # 有意改动时重生成基线
|
|
@@ -200,7 +284,7 @@ uv run python benchmarks/perf_baseline.py
|
|
|
200
284
|
|
|
201
285
|
- `uv.lock` 随仓库提供(133 个包,按 Python 3.8.1+ 全范围解析),`uv sync` 按锁文件精确安装;
|
|
202
286
|
升级依赖用 `uv lock --upgrade`。
|
|
203
|
-
- `--matrix` 用 `uv run --no-project --with pymunk==
|
|
287
|
+
- `--matrix` 用 `uv run --no-project --with pymunk==X` 现开临时环境,三个版本各跑一遍全部测试,
|
|
204
288
|
**不需要手动准备两个 venv**、也不会污染当前环境(整轮约 15 秒)。
|
|
205
289
|
- 不想用 uv 也可以:`pip install -e ".[dev]"` 后 `python scripts/check.py`,效果相同。
|
|
206
290
|
|
|
@@ -277,7 +361,8 @@ sign(n) # n 的符号:1 / -1 / 0
|
|
|
277
361
|
|------|------|------|--------|
|
|
278
362
|
| `setup(width, height, world=None)` | 初始化一个世界:窗口、相机、精灵组、物理空间 | 宽、高(整数像素) | `Screen` |
|
|
279
363
|
| `update(world=None)` | 推进一帧(物理 → 逻辑 → 渲染) | - | - |
|
|
280
|
-
| `
|
|
364
|
+
| `run(loop, world=None)` | 推荐主循环:每帧执行 `loop()` 后自动 `update()`;网页版自动让出浏览器事件循环 | 每帧函数 | - |
|
|
365
|
+
| `done(world=None)` | 进入死循环,直到关窗(网页端改为空转的 `run()`) | - | - |
|
|
281
366
|
| `title(text)` | 设置窗口标题 | 文本 | - |
|
|
282
367
|
| `save_screen(path, world=None)` | 把下一帧画面保存为图片 | 路径 | - |
|
|
283
368
|
| `init()` | 初始化 pygame / mixer / font(幂等,一般由 `setup()` 调用) | - | - |
|
|
@@ -1012,7 +1097,8 @@ uv run python examples/tiledmap_basics.py # TMX 地图当背景 + 对象
|
|
|
1012
1097
|
- [ ] 插件 / 组件系统
|
|
1013
1098
|
- [ ] 常用 UI 控件(按钮、输入框、列表…)
|
|
1014
1099
|
- [ ] 触控 / 移动端手势
|
|
1015
|
-
- [
|
|
1100
|
+
- [x] **HTML5 打包(实验性)**:`walimaker build game.py --web`(pygbag + WebAssembly + pymunk 6.4.0)
|
|
1101
|
+
- 后续:自建运行时镜像(减少对 pygbag CDN 的依赖)、桌面端一键打包(PyInstaller)
|
|
1016
1102
|
- [ ] 3D 渲染扩展(基于 OpenGL)
|
|
1017
1103
|
- [ ] 网络多人游戏支持
|
|
1018
1104
|
|
|
@@ -34,7 +34,9 @@ classifiers = [
|
|
|
34
34
|
]
|
|
35
35
|
dependencies = [
|
|
36
36
|
"pygame>=2.5.0",
|
|
37
|
-
|
|
37
|
+
# 网页版(pygbag 3.13)目前提供的是 pymunk 6.4.0 的 wasm 轮子;
|
|
38
|
+
# 桌面矩阵也已用 6.4.0 跑通全部测试,因此最低版本下调到 6.4.0。
|
|
39
|
+
"pymunk>=6.4.0",
|
|
38
40
|
"pytmx>=3.32",
|
|
39
41
|
]
|
|
40
42
|
|
|
@@ -61,11 +63,16 @@ docs = [
|
|
|
61
63
|
"mkdocs>=1.4",
|
|
62
64
|
"mkdocs-material>=9.0",
|
|
63
65
|
]
|
|
66
|
+
web = [
|
|
67
|
+
# HTML5 打包工具;只在 `walimaker build --web` 时需要
|
|
68
|
+
"pygbag>=0.9.3",
|
|
69
|
+
]
|
|
64
70
|
|
|
65
71
|
[project.urls]
|
|
66
72
|
PyPI = "https://pypi.org/project/walimaker/"
|
|
67
73
|
|
|
68
74
|
[project.scripts]
|
|
75
|
+
walimaker = "Walimaker.build:main"
|
|
69
76
|
walimaker-demo = "Walimaker.test:main"
|
|
70
77
|
|
|
71
78
|
# 标准 src 布局:源码位于 src/Walimaker/,打包时把 src 作为包查找根
|
|
@@ -71,7 +71,7 @@ from .music import (
|
|
|
71
71
|
)
|
|
72
72
|
from .objects import Character, GameObject, Mouse, NewGameObject, Object, Sensor, Wall
|
|
73
73
|
from .physics import Body, BodiesGroup, TiledMapBodies, TiledMapBodiesGroup
|
|
74
|
-
from .screen import Screen, done, save_screen, setup, title, update
|
|
74
|
+
from .screen import Screen, done, run, save_screen, setup, title, update
|
|
75
75
|
from .sprite import (
|
|
76
76
|
AnimatorStrategy,
|
|
77
77
|
EasySpriteStrategy,
|
|
@@ -94,6 +94,7 @@ __all__ = [
|
|
|
94
94
|
"Mouse",
|
|
95
95
|
"setup",
|
|
96
96
|
"update",
|
|
97
|
+
"run",
|
|
97
98
|
"title",
|
|
98
99
|
"done",
|
|
99
100
|
"save_screen",
|