gamekit2d 0.2.0__tar.gz

gamekit2d-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gamekit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gamekit2d-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# 打包进 sdist 源码包的额外内容
+include README.md
+include TUTORIAL.md
+include TUTORIAL.html
+include LICENSE
+include pyproject.toml
+recursive-include examples *.py
+recursive-include examples/assets *.png
+recursive-include tests *.py

gamekit2d-0.2.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: gamekit2d
+Version: 0.2.0
+Summary: A tiny zero-dependency 2D game library (standard library only, tkinter + winsound). A simpler pygame.
+Author: gamekit contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-name/gamekit
+Project-URL: Repository, https://github.com/your-name/gamekit
+Keywords: game,2d,game-engine,tkinter,zero-dependency,pygame-alternative
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gamekit
+
+> 一个**零第三方依赖**的极简 2D 游戏库 —— 只使用 Python 标准库，API 简单到极致，功能却相当齐全。
+
+gamekit 的目标是：**让任何人用最少的代码，最快做出一个能玩的 2D 小游戏**。不需要懂窗口、事件循环、坐标系等底层细节，一个文件就能跑起一个完整游戏。
+
+- 🚫 **零依赖**：只用 Python 标准库（`tkinter` 渲染 / `winsound` 音频），装好 Python 就能跑
+- ✨ **极简 API**：`Game` 一个类搞定窗口、输入、精灵、碰撞、物理、音效、粒子、场景
+- 🎮 **功能齐全**：精灵 / 图像 / 动画 / 碰撞 / 重力 / 音效 / 文字 / 按钮 / 进度条 / 粒子 / 场景切换
+- 🪶 **轻量**：纯 Python 实现，核心约 2000 行，结构清晰可读
+
+---
+
+## 安装
+
+### 方式一：直接使用源码（推荐，零配置）
+
+把 `gamekit/` 目录放到你的项目旁边，然后直接 `import gamekit`：
+
+```bash
+git clone https://github.com/your-name/gamekit.git
+cd gamekit
+python examples/01_hello.py          # 直接运行示例
+```
+
+### 方式二：pip 安装
+
+```bash
+pip install gamekit
+```
+
+> 无论哪种方式都**不需要安装任何第三方包**。运行环境只需 Python 3.9+（Windows / Linux / macOS 均可，音频仅 Windows 支持，其他平台自动静默降级）。
+
+---
+
+## 快速上手
+
+这是你能写出的最短游戏 —— **40 秒学会**：
+
+```python
+from gamekit import Game, Key
+
+# 1. 创建游戏
+game = Game(title="我的第一个游戏", width=800, height=600, fps=60)
+
+# 2. 创建精灵（一个红色矩形）
+player = game.sprite(color="red", x=400, y=300, width=60, height=40)
+
+# 3. 绑定按键
+@game.on_key(Key.LEFT)
+def left():
+    player.vx = -300
+
+@game.on_key(Key.RIGHT)
+def right():
+    player.vx = 300
+
+@game.on_key(Key.SPACE)
+def stop():
+    player.vx = 0
+
+# 4. 启动游戏
+game.run()
+```
+
+运行后：按 ← → 移动方块，按空格停下。**一个可玩的游戏就完成了。**
+
+---
+
+## 功能总览
+
+| 功能 | 说明 | 快速示例 |
+|---|---|---|
+| 🖼 精灵 | 图像 / 纯色 / 圆形，位置速度、旋转缩放 | `game.sprite("player.png", x=100, y=100)` |
+| ⌨️ 键盘 | 按下 / 抬起 / 持续按住 | `@game.on_key(Key.SPACE)` |
+| 🖱 鼠标 | 移动 / 点击 / 滚轮 | `@game.on_mouse_click` |
+| 💥 碰撞 | 矩形 + 圆形，自动检测进入瞬间 | `@game.on_collide(player, "coin")` |
+| 🌍 物理 | 重力、摩擦、反弹、屏幕边界 | `sprite.gravity_scale = 1.0` |
+| 🎞 动画 | 多帧图像循环播放 | `sprite.play(["a.png", "b.png"], fps=8)` |
+| 🔊 音频 | WAV 音效 / 循环背景乐 | `game.sound("hit.wav").play()` |
+| 📝 文字 | 任意字体 / 字号 / 加粗 | `game.text("得分 0", x=30, y=30)` |
+| 🔘 UI | 按钮（悬停高亮）、进度条 | `game.button("开始", on_click=fn)` |
+| ✨ 粒子 | 爆炸 / 火花 / 飘雪 | `game.burst(x, y, count=40)` |
+| 🎬 场景 | 菜单 / 关卡 / 结束画面切换 | `game.switch_scene(MyScene())` |
+| ⏱ 定时器 | 延迟调用 / 周期调用 | `game.every(0.5, fn)` |
+
+---
+
+## 完整示例：收集金币
+
+一个集精灵、物理、碰撞、粒子、计分于一体的微型游戏（约 30 行）：
+
+```python
+from gamekit import Game, Key
+
+game = Game(title="收集金币", width=800, height=600, fps=60)
+game.bg_color = "#141a24"
+game.gravity = 600
+
+# 玩家（受重力）
+player = game.sprite(color="#4ac0f0", x=400, y=300, width=44, height=44)
+player.gravity_scale = 1.0
+player.keep_on_screen = True
+
+# 地面
+ground = game.sprite(color="#2a3342", x=400, y=580, width=800, height=40)
+
+# 金币
+score = [0]
+score_text = game.text("金币：0", x=400, y=30, size=24, bold=True)
+coin_n = [0]
+
+def spawn_coin():
+    coin_n[0] += 1
+    return game.sprite(color="#ffd700", x=60 + (coin_n[0] * 61) % 680,
+                       y=400 + (coin_n[0] * 23) % 130,
+                       width=26, height=26, shape="circle", tag="coin")
+
+for _ in range(8):
+    spawn_coin()
+
+@game.on_key(Key.SPACE)
+def jump():
+    if player.bottom >= ground.top - 2:
+        player.vy = -420
+
+@game.on_key_hold(Key.LEFT)
+def move_left():
+    player.vx = -260
+
+@game.on_key_hold(Key.RIGHT)
+def move_right():
+    player.vx = 260
+
+@game.on_key(Key.ESCAPE)
+def quit_game():
+    game.stop()
+
+@game.on_collide(player, ground)
+def land(p, g):
+    if p.vy > 0:                      # 只在向下落时落地
+        p.y = g.top - p.height / 2
+        p.vy = 0
+
+@game.on_collide(player, "coin")
+def collect(p, c):
+    c.remove()
+    score[0] += 1
+    game.burst(c.x, c.y, count=18, colors=("gold", "white", "orange"))
+    score_text.set("金币：%d" % score[0])
+
+game.run()
+```
+
+---
+
+## 运行示例小游戏
+
+项目自带 4 个由浅入深的完整示例（`examples/` 目录）：
+
+```bash
+python examples/01_hello.py        # 最小游戏：反弹小球 + 暂停/变色
+python examples/02_pong.py         # 双人乒乓球（键盘对战）
+python examples/03_breakout.py     # 打砖块（完整小游戏：场景/UI/粒子/计分/生命）
+python examples/04_sprite_image.py # 图像精灵：旋转/缩放/帧动画
+python examples/05_space_shooter.py# 太空射击（综合实战：键盘/碰撞/粒子/场景）
+```
+
+> 使用图像精灵的示例请先运行 `python examples/make_assets.py` 生成素材。
+
+---
+
+## 📖 完整教程
+
+想从零系统学习？请看 **[TUTORIAL.md](TUTORIAL.md)** —— 13 章手把手教程，
+从"第一个窗口"到"完整太空射击游戏"，每章代码都可直接运行。
+
+---
+
+## API 速查
+
+### Game（游戏）
+
+```python
+Game(title="标题", width=800, height=600, fps=60, bg_color="#14141a")
+game.run() / game.stop()
+game.sprite(...)      # 创建精灵
+game.text(...)        # 创建文字
+game.button(...)      # 创建按钮
+game.progress_bar(...)# 创建进度条
+game.sound(path)      # 加载音效
+game.music(path)      # 加载循环背景乐
+game.particles(...)   # 粒子系统
+game.burst(x, y, ...) # 一次粒子爆发
+game.add_scene(s) / game.switch_scene(s)   # 场景管理
+game.after(sec, fn) / game.every(sec, fn)  # 定时器
+game.gravity          # 全局重力（像素/秒²）
+game.dt / game.time   # 帧耗时 / 累计时间
+game.is_key_down(key) # 按键是否按住
+game.find(tag)        # 按标签查找精灵
+```
+
+### 事件装饰器
+
+```python
+@game.on_update                    # 每帧更新  fn(dt)
+@game.on_key(Key.SPACE)            # 按键按下  fn()
+@game.on_key_up(Key.SPACE)         # 按键抬起  fn()
+@game.on_key_hold(Key.LEFT)        # 按住持续  fn(dt)
+@game.on_mouse_click               # 左键点击  fn(x, y)
+@game.on_mouse_move                # 鼠标移动  fn(x, y)
+@game.on_mouse_down / up           # 按下/抬起 fn(x, y, button)
+@game.on_mouse_wheel               # 滚轮      fn(delta, x, y)
+@game.on_collide(a, b)             # 碰撞进入  fn(a, b)  a/b 可为精灵或标签
+```
+
+### Sprite（精灵）
+
+```python
+s = game.sprite(image="a.png" | color="red", x=0, y=0,
+                width=40, height=40, shape="rect|circle", tag="enemy")
+s.x / s.y / s.vx / s.vy            # 位置与速度（像素/秒）
+s.move(dx, dy) / s.move_to(x, y)
+s.set_scale(f) / s.set_angle(deg)  # 缩放 / 旋转（图像精灵）
+s.play([f1, f2], fps=8, loop=True) # 帧动画
+s.hide() / s.show() / s.remove()
+s.collides_with(other)             # 是否碰撞
+s.bounce_off(other)                # 按重叠方向反弹
+s.gravity_scale / s.friction / s.bounce / s.keep_on_screen
+s.on_update = lambda dt: ...       # 单精灵每帧逻辑
+```
+
+### Key（按键常量）
+
+```python
+Key.SPACE / Key.UP / Key.DOWN / Key.LEFT / Key.RIGHT
+Key.ENTER / Key.ESC / Key.TAB / Key.BACKSPACE
+Key.SHIFT / Key.CTRL / Key.ALT
+Key.A ~ Key.Z  /  Key.F1 ~ Key.F12
+```
+
+也可以直接传字符串：`"space"`、`"a"`、`"F5"`（大小写均可）。
+
+---
+
+## 项目结构
+
+```
+gamekit/
+├── gamekit/
+│   ├── core/        # 核心引擎：Game 主类、场景、事件、按键
+│   ├── sprites/     # 精灵、图像处理（自研缩放/旋转）、帧动画
+│   ├── physics/     # 碰撞检测（矩形/圆形）
+│   ├── audio/       # WAV 音效（winsound）
+│   ├── ui/          # 文字、按钮、进度条
+│   ├── fx/          # 粒子系统
+│   └── utils/       # 颜色、向量工具
+├── examples/        # 4 个完整示例 + 素材生成脚本
+├── tests/           # 单元测试 + GUI 冒烟测试
+├── pyproject.toml   # 发布配置（零依赖）
+└── README.md
+```
+
+---
+
+## 已知限制（标准库方案的能力边界）
+
+由于坚持零第三方依赖，有以下取舍，**请按需评估**：
+
+| 能力 | 限制 | 说明 |
+|---|---|---|
+| 音频 | 仅 `.wav`，仅 Windows，一次一个 | 标准库 `winsound` 的能力边界；其他平台自动静默 |
+| 图像格式 | PNG / GIF / PPM / BMP | 不支持 JPG（Tk 无解码器），可用 PNG 替代 |
+| 旋转/缩放 | 最近邻算法，大图较慢 | 适合 200×200 以下的小图，在加载时调用一次 |
+| 渲染性能 | 每帧全量重绘 | 适合教学、原型、小规模游戏；大量精灵（>500）会掉帧 |
+
+---
+
+## 测试
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"   # 单元测试（碰撞/颜色/向量/按键）
+python tests/run_selftest.py                          # GUI 冒烟测试（自动运行 120 帧）
+```
+
+---
+
+## 许可
+
+[MIT](LICENSE) © gamekit contributors
+
+用游戏kit，做个游戏吧 🎮

gamekit2d-0.2.0/README.md

@@ -0,0 +1,292 @@
+# gamekit
+
+> 一个**零第三方依赖**的极简 2D 游戏库 —— 只使用 Python 标准库，API 简单到极致，功能却相当齐全。
+
+gamekit 的目标是：**让任何人用最少的代码，最快做出一个能玩的 2D 小游戏**。不需要懂窗口、事件循环、坐标系等底层细节，一个文件就能跑起一个完整游戏。
+
+- 🚫 **零依赖**：只用 Python 标准库（`tkinter` 渲染 / `winsound` 音频），装好 Python 就能跑
+- ✨ **极简 API**：`Game` 一个类搞定窗口、输入、精灵、碰撞、物理、音效、粒子、场景
+- 🎮 **功能齐全**：精灵 / 图像 / 动画 / 碰撞 / 重力 / 音效 / 文字 / 按钮 / 进度条 / 粒子 / 场景切换
+- 🪶 **轻量**：纯 Python 实现，核心约 2000 行，结构清晰可读
+
+---
+
+## 安装
+
+### 方式一：直接使用源码（推荐，零配置）
+
+把 `gamekit/` 目录放到你的项目旁边，然后直接 `import gamekit`：
+
+```bash
+git clone https://github.com/your-name/gamekit.git
+cd gamekit
+python examples/01_hello.py          # 直接运行示例
+```
+
+### 方式二：pip 安装
+
+```bash
+pip install gamekit
+```
+
+> 无论哪种方式都**不需要安装任何第三方包**。运行环境只需 Python 3.9+（Windows / Linux / macOS 均可，音频仅 Windows 支持，其他平台自动静默降级）。
+
+---
+
+## 快速上手
+
+这是你能写出的最短游戏 —— **40 秒学会**：
+
+```python
+from gamekit import Game, Key
+
+# 1. 创建游戏
+game = Game(title="我的第一个游戏", width=800, height=600, fps=60)
+
+# 2. 创建精灵（一个红色矩形）
+player = game.sprite(color="red", x=400, y=300, width=60, height=40)
+
+# 3. 绑定按键
+@game.on_key(Key.LEFT)
+def left():
+    player.vx = -300
+
+@game.on_key(Key.RIGHT)
+def right():
+    player.vx = 300
+
+@game.on_key(Key.SPACE)
+def stop():
+    player.vx = 0
+
+# 4. 启动游戏
+game.run()
+```
+
+运行后：按 ← → 移动方块，按空格停下。**一个可玩的游戏就完成了。**
+
+---
+
+## 功能总览
+
+| 功能 | 说明 | 快速示例 |
+|---|---|---|
+| 🖼 精灵 | 图像 / 纯色 / 圆形，位置速度、旋转缩放 | `game.sprite("player.png", x=100, y=100)` |
+| ⌨️ 键盘 | 按下 / 抬起 / 持续按住 | `@game.on_key(Key.SPACE)` |
+| 🖱 鼠标 | 移动 / 点击 / 滚轮 | `@game.on_mouse_click` |
+| 💥 碰撞 | 矩形 + 圆形，自动检测进入瞬间 | `@game.on_collide(player, "coin")` |
+| 🌍 物理 | 重力、摩擦、反弹、屏幕边界 | `sprite.gravity_scale = 1.0` |
+| 🎞 动画 | 多帧图像循环播放 | `sprite.play(["a.png", "b.png"], fps=8)` |
+| 🔊 音频 | WAV 音效 / 循环背景乐 | `game.sound("hit.wav").play()` |
+| 📝 文字 | 任意字体 / 字号 / 加粗 | `game.text("得分 0", x=30, y=30)` |
+| 🔘 UI | 按钮（悬停高亮）、进度条 | `game.button("开始", on_click=fn)` |
+| ✨ 粒子 | 爆炸 / 火花 / 飘雪 | `game.burst(x, y, count=40)` |
+| 🎬 场景 | 菜单 / 关卡 / 结束画面切换 | `game.switch_scene(MyScene())` |
+| ⏱ 定时器 | 延迟调用 / 周期调用 | `game.every(0.5, fn)` |
+
+---
+
+## 完整示例：收集金币
+
+一个集精灵、物理、碰撞、粒子、计分于一体的微型游戏（约 30 行）：
+
+```python
+from gamekit import Game, Key
+
+game = Game(title="收集金币", width=800, height=600, fps=60)
+game.bg_color = "#141a24"
+game.gravity = 600
+
+# 玩家（受重力）
+player = game.sprite(color="#4ac0f0", x=400, y=300, width=44, height=44)
+player.gravity_scale = 1.0
+player.keep_on_screen = True
+
+# 地面
+ground = game.sprite(color="#2a3342", x=400, y=580, width=800, height=40)
+
+# 金币
+score = [0]
+score_text = game.text("金币：0", x=400, y=30, size=24, bold=True)
+coin_n = [0]
+
+def spawn_coin():
+    coin_n[0] += 1
+    return game.sprite(color="#ffd700", x=60 + (coin_n[0] * 61) % 680,
+                       y=400 + (coin_n[0] * 23) % 130,
+                       width=26, height=26, shape="circle", tag="coin")
+
+for _ in range(8):
+    spawn_coin()
+
+@game.on_key(Key.SPACE)
+def jump():
+    if player.bottom >= ground.top - 2:
+        player.vy = -420
+
+@game.on_key_hold(Key.LEFT)
+def move_left():
+    player.vx = -260
+
+@game.on_key_hold(Key.RIGHT)
+def move_right():
+    player.vx = 260
+
+@game.on_key(Key.ESCAPE)
+def quit_game():
+    game.stop()
+
+@game.on_collide(player, ground)
+def land(p, g):
+    if p.vy > 0:                      # 只在向下落时落地
+        p.y = g.top - p.height / 2
+        p.vy = 0
+
+@game.on_collide(player, "coin")
+def collect(p, c):
+    c.remove()
+    score[0] += 1
+    game.burst(c.x, c.y, count=18, colors=("gold", "white", "orange"))
+    score_text.set("金币：%d" % score[0])
+
+game.run()
+```
+
+---
+
+## 运行示例小游戏
+
+项目自带 4 个由浅入深的完整示例（`examples/` 目录）：
+
+```bash
+python examples/01_hello.py        # 最小游戏：反弹小球 + 暂停/变色
+python examples/02_pong.py         # 双人乒乓球（键盘对战）
+python examples/03_breakout.py     # 打砖块（完整小游戏：场景/UI/粒子/计分/生命）
+python examples/04_sprite_image.py # 图像精灵：旋转/缩放/帧动画
+python examples/05_space_shooter.py# 太空射击（综合实战：键盘/碰撞/粒子/场景）
+```
+
+> 使用图像精灵的示例请先运行 `python examples/make_assets.py` 生成素材。
+
+---
+
+## 📖 完整教程
+
+想从零系统学习？请看 **[TUTORIAL.md](TUTORIAL.md)** —— 13 章手把手教程，
+从"第一个窗口"到"完整太空射击游戏"，每章代码都可直接运行。
+
+---
+
+## API 速查
+
+### Game（游戏）
+
+```python
+Game(title="标题", width=800, height=600, fps=60, bg_color="#14141a")
+game.run() / game.stop()
+game.sprite(...)      # 创建精灵
+game.text(...)        # 创建文字
+game.button(...)      # 创建按钮
+game.progress_bar(...)# 创建进度条
+game.sound(path)      # 加载音效
+game.music(path)      # 加载循环背景乐
+game.particles(...)   # 粒子系统
+game.burst(x, y, ...) # 一次粒子爆发
+game.add_scene(s) / game.switch_scene(s)   # 场景管理
+game.after(sec, fn) / game.every(sec, fn)  # 定时器
+game.gravity          # 全局重力（像素/秒²）
+game.dt / game.time   # 帧耗时 / 累计时间
+game.is_key_down(key) # 按键是否按住
+game.find(tag)        # 按标签查找精灵
+```
+
+### 事件装饰器
+
+```python
+@game.on_update                    # 每帧更新  fn(dt)
+@game.on_key(Key.SPACE)            # 按键按下  fn()
+@game.on_key_up(Key.SPACE)         # 按键抬起  fn()
+@game.on_key_hold(Key.LEFT)        # 按住持续  fn(dt)
+@game.on_mouse_click               # 左键点击  fn(x, y)
+@game.on_mouse_move                # 鼠标移动  fn(x, y)
+@game.on_mouse_down / up           # 按下/抬起 fn(x, y, button)
+@game.on_mouse_wheel               # 滚轮      fn(delta, x, y)
+@game.on_collide(a, b)             # 碰撞进入  fn(a, b)  a/b 可为精灵或标签
+```
+
+### Sprite（精灵）
+
+```python
+s = game.sprite(image="a.png" | color="red", x=0, y=0,
+                width=40, height=40, shape="rect|circle", tag="enemy")
+s.x / s.y / s.vx / s.vy            # 位置与速度（像素/秒）
+s.move(dx, dy) / s.move_to(x, y)
+s.set_scale(f) / s.set_angle(deg)  # 缩放 / 旋转（图像精灵）
+s.play([f1, f2], fps=8, loop=True) # 帧动画
+s.hide() / s.show() / s.remove()
+s.collides_with(other)             # 是否碰撞
+s.bounce_off(other)                # 按重叠方向反弹
+s.gravity_scale / s.friction / s.bounce / s.keep_on_screen
+s.on_update = lambda dt: ...       # 单精灵每帧逻辑
+```
+
+### Key（按键常量）
+
+```python
+Key.SPACE / Key.UP / Key.DOWN / Key.LEFT / Key.RIGHT
+Key.ENTER / Key.ESC / Key.TAB / Key.BACKSPACE
+Key.SHIFT / Key.CTRL / Key.ALT
+Key.A ~ Key.Z  /  Key.F1 ~ Key.F12
+```
+
+也可以直接传字符串：`"space"`、`"a"`、`"F5"`（大小写均可）。
+
+---
+
+## 项目结构
+
+```
+gamekit/
+├── gamekit/
+│   ├── core/        # 核心引擎：Game 主类、场景、事件、按键
+│   ├── sprites/     # 精灵、图像处理（自研缩放/旋转）、帧动画
+│   ├── physics/     # 碰撞检测（矩形/圆形）
+│   ├── audio/       # WAV 音效（winsound）
+│   ├── ui/          # 文字、按钮、进度条
+│   ├── fx/          # 粒子系统
+│   └── utils/       # 颜色、向量工具
+├── examples/        # 4 个完整示例 + 素材生成脚本
+├── tests/           # 单元测试 + GUI 冒烟测试
+├── pyproject.toml   # 发布配置（零依赖）
+└── README.md
+```
+
+---
+
+## 已知限制（标准库方案的能力边界）
+
+由于坚持零第三方依赖，有以下取舍，**请按需评估**：
+
+| 能力 | 限制 | 说明 |
+|---|---|---|
+| 音频 | 仅 `.wav`，仅 Windows，一次一个 | 标准库 `winsound` 的能力边界；其他平台自动静默 |
+| 图像格式 | PNG / GIF / PPM / BMP | 不支持 JPG（Tk 无解码器），可用 PNG 替代 |
+| 旋转/缩放 | 最近邻算法，大图较慢 | 适合 200×200 以下的小图，在加载时调用一次 |
+| 渲染性能 | 每帧全量重绘 | 适合教学、原型、小规模游戏；大量精灵（>500）会掉帧 |
+
+---
+
+## 测试
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"   # 单元测试（碰撞/颜色/向量/按键）
+python tests/run_selftest.py                          # GUI 冒烟测试（自动运行 120 帧）
+```
+
+---
+
+## 许可
+
+[MIT](LICENSE) © gamekit contributors
+
+用游戏kit，做个游戏吧 🎮