Metadata-Version: 2.2
Name: tkunity
Version: 2026.11.1.dev0
Summary: tkunity - 纯标准库的 Unity 风格 2D 游戏编辑器与运行时：组件、父子层级、预制体、刚体物理、碰撞触发器、生命周期脚本、摄像机，可把 .pyu 游戏导出为 Android APK 工程（Apache 2.0, oiiaio-web）
Author: oiiaio-web
Author-email: oiiaio-web <3926580760@qq.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/oiiaio-web/tkunity
Project-URL: Bug Tracker, https://github.com/oiiaio-web/tkunity/issues
Keywords: game,editor,tkinter,unity,android,apk,2d
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: requires-python

# tkunity

> 纯标准库、零第三方依赖（不需要 pygame）的 **Unity 风格 2D 游戏编辑器 + 运行时**，
> 把你在编辑器里拼出来的 `.pyu` 游戏一键导出成 **Android APK 工程**。

- **许可证**：Apache License 2.0
- **作者**：oiiaio-web <3926580760@qq.com>
- **版本**：2026.11.1.dev0
- **Python**：>= 3.8（已在 3.8 / 3.14 / 3.15 / 3.16 上测试）
- **依赖**：**零**。只使用标准库 `tkinter / json / base64 / argparse / math`。Linux 上若缺少 tk 图形环境，请安装系统包 `python3-tk`（这不是 pip 依赖）。

---

## 一、这一版「更像 Unity」的地方

| Unity 概念 | tkunity 对应实现 |
|---|---|
| GameObject + Component | 实体 + 可增删组件（组件表驱动，Inspector 自动生成） |
| Transform 父子层级 | 实体 `parent` 字段，子物体跟随父物体的位移与缩放 |
| Prefab | 预制体库：存 / 实例化 / 生成器批量刷怪 |
| Rigidbody2D | 刚体：重力、速度、阻尼、弹性、dynamic / kinematic / static |
| BoxCollider2D | AABB 碰撞推出 + 触发器（`on_collision` 回调） |
| MonoBehaviour | Script 组件：`on_start / on_update / on_tap / on_collision / on_destroy` |
| Camera | Camera2D：跟随目标 + 缩放 + 平滑 |
| Animator | Animator：spin / pulse / fade / slide / float 补间 |
| Tag | 每个物体的 `tag` 标签，可按标签筛选 |
| Play / Pause / Step | 预览窗口的暂停·继续、单步、重启 |
| Hierarchy / Inspector / Console | 编辑器左树 / 右属性面板 / 底部控制台 |
| Undo / Redo | Ctrl+Z / Ctrl+Y（60 步快照） |

---

## 二、安装

```bash
pip install tkunity        # 从 PyPI
# 或从源码目录
pip install -e .
tkunity --version          # 查看版本
tkunity -h / -help / --help   # 三种写法功能一样
```

不需要 pygame、不需要 Kivy、不需要任何 pip 第三方包。

---

## 三、命令行

```bash
tkunity                          # 打开图形编辑器
tkunity edit examples/demo.pyu   # 打开编辑器并载入项目
tkunity new 游戏.pyu --width 960 --height 640
tkunity run 游戏.pyu             # 直接运行（桌面预览）
tkunity validate 游戏.pyu        # 校验组件 / 父子环 / 预制体引用
tkunity build 游戏.pyu -o out    # 导出 Android 工程
tkunity info                     # 环境与组件信息
```

---

## 四、编辑器

```
┌──────────────────── 工具栏：文件 / 撤销重做 / 预览 / 导出 ─────────────────────┐
│ 层级(父子树) │         场景画布（缩放 / 网格吸附）        │  Inspector        │
│ ＋空物体     │                                           │  名称 / 标签 / 激活 │
│ 零件库       │                                           │  父物体            │
│ 预制体       │                                           │  各组件字段        │
├──────────────┴───────────────────────────────────────────┴───────────────────┤
│ 控制台（运行日志 / 脚本输出）                                                │
└──────────────────────────────────────────────────────────────────────────────┘
```

**常用操作**

| 操作 | 方式 |
|---|---|
| 放置零件 | 左侧零件库单击 → 画布单击；或双击零件放到画布中心 |
| 选中 / 拖动 / 缩放 | 画布单击物体、拖拽移动、右下角绿点缩放 |
| 精确改数值 | 右侧 Inspector 改字段 → 点「应用」 |
| 添加 / 移除组件 | Inspector 底部下拉「添加组件」；组件标题栏「移除」 |
| 建立父子 | 先选中子物体，在 Inspector「父物体」下拉里选父级 |
| 存预制体 | Inspector「存为预制体」 |
| 实例化预制体 | 左下预制体列表双击 |
| 复制 / 删除 | Ctrl+D / Delete |
| 微调位置 | 方向键（一次一格） |
| 撤销 / 重做 | Ctrl+Z / Ctrl+Y |
| 试玩 | 工具栏「预览」→ 暂停 / 继续、单步、重启 |

---

## 五、组件参考

| 组件 | 字段 |
|---|---|
| **Transform** | x, y, width, height, rotation, scale, layer（绘制层级） |
| **Sprite** | shape(rect/oval/image), fill, outline, image, opacity |
| **Label** | text, font_size, color, bold, align(center/left/right) |
| **Animator** | effect(spin/pulse/fade/slide/float), speed, amplitude, auto_play |
| **Rigidbody2D** | body_type, velocity_x, velocity_y, gravity_scale, drag, bounce, fixed_rotation |
| **BoxCollider2D** | is_trigger, offset_x, offset_y, width, height（0 = 跟随 Transform） |
| **TapHandler** | action |
| **Timer** | interval_ms, action, auto_start, repeat |
| **Script** | name, on_start, on_update, on_tap, on_collision, on_destroy |
| **Spawner** | prefab, interval_ms, max_alive, offset_x, offset_y |
| **Camera2D** | follow（物体名）, zoom, smooth |

---

## 六、内置动作

可用于 `TapHandler.action`、`Timer.action`：

```
none                    什么都不做
move-left / move-right / move-up / move-down   设置速度 240 px/s
jump                    向上初速度 430 px/s
bounce                  首次触发时给一个对角速度
stop                    速度归零
destroy                 销毁自己
toggle                  切换自身激活状态
restart                 重开场景
spawn:<预制体名>         在自己位置实例化预制体
print('文字')            打印到控制台 / logcat
```

桌面预览额外支持 Python 表达式，例如 `x += 10`、`width = 200`、`log('hp=%d' % hp)`。

> 导出 APK 时只保留上表的内置动作；自定义 Python 表达式与 Script 组件仅在桌面预览生效。

---

## 七、脚本（桌面预览）

`Script` 组件的每个生命周期都跑在受限命名空间里：

| 可用名字 | 含义 |
|---|---|
| `self` / `entity` | 当前实体字典 |
| `scene` | 运行时场景对象（`scene.axis()`、`scene.find()` 等） |
| `x`, `y`, `width`, `height`, `w`, `h` | 位置与尺寸，执行后自动写回 |
| `vx`, `vy` | 速度（px/s），自动写回刚体 |
| `rotation`, `scale` | 旋转与缩放 |
| `dt`, `time` | 帧间隔（秒）、运行时长（秒） |
| `log(msg)` | 输出到控制台 |
| `find(name)` | 按名字找实体 |
| `spawn(prefab, x, y)` | 实例化预制体 |
| `destroy(target)` | 销毁实体 |
| `other` | 碰撞回调里的对方实体 |
| `math` | 数学模块 |

例：键盘控制左右移动

```python
# on_update
x += scene.axis("horizontal") * 260 * dt
if y > 560:
    restart()
```

---

## 八、Python API

```python
from tkunity import Project, GameObject, save

p = Project("弹球", 960, 640, background="#1e1e2e", gravity=980)

ground = GameObject("地面", 0, 560, 960, 40, tag="Ground")
ground.add_sprite("rect", fill="#45475a").add_collider()
p.add(ground)

ball = GameObject("球", 460, 100, 60, 60, tag="Player")
ball.add_sprite("oval", fill="#f38ba8")
ball.add_rigidbody(velocity_x=160, bounce=0.9)
ball.add_collider()
ball.add_animator("spin", speed=0.6)
ball.add_script(on_update="if x < 0 or x + w > 960: vx = -vx")
p.add(ball)

p.save_prefab(ball, "ball")      # 存成预制体
p.instantiate("ball", 200, 80)   # 再实例化一个
save(p, "demo.pyu")
```

### 项目 / 物体 API

| 方法 | 说明 |
|---|---|
| `Project(name, w, h, background, gravity)` | 新建项目（一个 `.pyu` = 一个场景） |
| `Project.add(obj, parent=...)` | 加入物体，可指定父物体 |
| `Project.find(name)` / `Project.tag(tag)` | 按名字 / 标签查找 |
| `Project.save_prefab(obj, name)` / `instantiate(name, x, y)` | 预制体 |
| `Project.set_scene(...)` / `set_physics(gravity=..., time_scale=...)` | 场景与物理设置 |
| `Project.embed_image(path)` | 内嵌 PNG/GIF |
| `Project.world_rect(obj)` | 世界坐标包围盒 |
| `Project.save(path)` / `tkunity.save(p, path)` | 保存 |
| `GameObject.add_sprite / add_label / add_animator / add_rigidbody / add_collider / add_tap / add_timer / add_script / add_spawner / add_camera` | 加组件（链式） |
| `GameObject.set_parent(parent)` / `move(dx,dy)` / `set_position / set_size / set_rotation` | 变换 |

---

## 九、导出 Android

```bash
tkunity build examples/demo.pyu -o ./out
cd out/android_*
# 设置 ANDROID_HOME 或在目录里放 local.properties
build_apk.bat        # Windows
./build_apk.sh       # Linux / macOS
# 产物 app/build/outputs/apk/debug/app-debug.apk
```

导出的 Java 渲染器（`GameView.java`）零第三方依赖，支持层级、旋转缩放、
刚体物理、碰撞触发器、摄像机、动画与全部内置动作。

---

## 十、限制

- 2D 简化模型：父物体的旋转不参与子物体位置计算（位移与缩放参与）；
- `tkinter` Canvas 不能真正旋转图片，图片精灵的旋转在桌面预览中表现为轴对齐，APK 中完整支持；
- Script 与自定义 Python 表达式不会导出到 APK（Java 侧不执行任意脚本）；
- 一个 `.pyu` 对应一个场景，暂不支持多场景切换。
