Metadata-Version: 2.4
Name: tkunity
Version: 2026.11.1
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: license-file
Dynamic: requires-python

# tkunity

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

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

---

## 一、安装

```bash
pip install -e .          # 从源码目录安装（或直接 pip install tkunity 发布后）
tkunity --version         # 查看版本
tkunity -h / -help / --help   # 三种写法功能一样，都显示帮助
```

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

---

## 二、快速上手

```bash
tkunity                     # 启动图形编辑器（左：零件库 / 中：网格画布 / 右：属性面板）
tkunity edit examples/demo.pyu
```

在编辑器里：

1. **左侧「零件库」**：点选一个零件（矩形 / 椭圆 / 文本 / 图片 / 点击触发器 / 定时器），再在中间网格上点一下即可放置；双击零件则放到画布中心。
2. **中间画布**：按住物体拖动移动位置（自动吸附网格 20px），右下角小方块可拖拽缩放，点选物体右侧出现属性。
3. **右侧「属性」**：修改名称、坐标、尺寸、颜色、文本、点击动作、定时器动作等；「应用」或按回车生效。
4. 工具栏：`新建 / 打开 / 保存 / 另存为`（项目文件后缀 **`.pyu`**）、`预览`、`导出APK`。

也可以用 API 纯代码建项目：

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

p = Project(name="弹球", scene_width=960, scene_height=640, background="#1e1e2e")
ball = GameObject("ball", x=200, y=200, width=60, height=60)
ball.add_sprite("oval", fill="#f38ba8", outline="#f9e2af")
ball.add_timer(16, "bounce")
p.add(ball)
save(p, "examples/demo.pyu")
```

命令行直接导出 APK 工程：

```bash
tkunity build examples/demo.pyu -o out/android_game
cd out/android_game && ./build_apk.sh   # 或 Windows 下 build_apk.bat
```

---

## 三、`.pyu` 项目文件格式

`.pyu` = 8 字节魔数 `TKU-PYU\x00\x01\n` + 一个 JSON 对象：

```json
{
  "meta":   { "tkunity_version": "2026.11.1", "name": "...", "scene_width": 960,
              "scene_height": 640, "background": "#1e1e2e" },
  "entities": [
    { "id": 1, "name": "ball",
      "components": {
        "Transform":   { "x": 200, "y": 200, "width": 60, "height": 60,
                         "rotation": 0.0, "layer": 0 },
        "Sprite":      { "shape": "oval", "fill": "#f38ba8",
                         "outline": "#f9e2af", "image": "" },
        "Label":       { "text": "", "font_size": 18, "color": "#000000", "bold": false },
        "TapHandler":  { "action": "none" },
        "Timer":       { "interval_ms": 16, "action": "bounce" }
      } }
  ],
  "assets": { "images/logo.png": "<base64 PNG 数据>" }
}
```

- 图片资源会 **base64 内嵌**进 `.pyu`，单文件自包含，拷走即走。
- 图片仅支持 **PNG / GIF**（tkinter 原生能力，无第三方库）。

### 组件一览

| 组件 | 字段 | 说明 |
|---|---|---|
| `Transform` | x, y, width, height, rotation, layer | 所有物体自动拥有，layer 决定绘制层级 |
| `Sprite` | shape(rect/oval/image), fill, outline, image | 视觉主体 |
| `Label` | text, font_size, color, bold | 文本，居中显示在物体内 |
| `TapHandler` | action | 点击动作（桌面预览支持 Python 表达式，x/y 为位置、width/height(w/h) 为大小变量，可直接 `x += 20` 移动、`w += 10` 缩放） |
| `Timer` | interval_ms, action | 定时动作（同样支持上面的位置/大小变量） |

---

## 四、导出 APK（关键说明）

`tkunity build xxx.pyu` 会生成一个**可直接用 Android Studio / Gradle 构建**的完整 Android 工程：

- 纯 **Java + org.json**，**零第三方依赖**，minSdk **26**（与你的设备习惯一致），targetSdk 34；
- `GameView` 用 `android.graphics.Canvas` 渲染场景：网格背景、rect/oval/图片、文本、层级、触摸拖拽、点击、定时器；
- 内置动作（桌面预览与 APK 通用）：`none`、`print(...)`、`move-left / move-right / move-up / move-down`（持续移动）、`bounce`（弹跳并碰边反弹）、`stop`。

> **诚实的边界**：`TapHandler/Timer` 里写的**自定义 Python 表达式只在桌面预览中运行**（tkinter 运行时用受限 `eval` 执行）。APK 是独立渲染器，只支持上表「内置动作」。复杂逻辑请用「多个物体 + 定时器 + 内置动作」组合实现，或导出工程后在 `GameView.java` 里扩展。

构建工程产物（每项都会生成）：

```
out/android_game/
├── settings.gradle  build.gradle  gradle.properties
├── app/build.gradle
├── app/src/main/AndroidManifest.xml
├── app/src/main/assets/game.pyu          # 游戏数据（含内嵌图片）
├── app/src/main/java/com/oiiaio/tkunity/
│   ├── MainActivity.java
│   └── GameView.java
├── build_apk.bat / build_apk.sh          # 自动下载 Gradle 8.5 并构建
└── README_BUILD.md
```

构建条件：JDK 17 + Android SDK（设置 `ANDROID_HOME`，或在工程里放 `local.properties: sdk.dir=...`）。构建后 APK 位于 `app/build/outputs/apk/debug/app-debug.apk`。

---

## 五、运行 API

```python
import tkunity
from tkunity.runtime import Scene
import tkinter as tk

root = tk.Tk()
game = Scene(root, tkunity.load("examples/demo.pyu"))
game.pack(fill="both", expand=True)
game.start()
root.mainloop()
```

---

## 六、目录结构

```
tkunity/
├── pyproject.toml / setup.py / LICENSE / README.md
├── tkunity/
│   ├── __init__.py      # 公共入口 Project/GameObject/save/load
│   ├── components.py    # 组件注册表与零件库
│   ├── pyu.py           # .pyu 序列化（含资源内嵌）
│   ├── api.py           # 面向对象建项目 API
│   ├── runtime.py       # tkinter 游戏运行时
│   ├── editor.py        # Unity 风格三栏编辑器
│   ├── export.py        # Android APK 工程生成器
│   ├── cli.py           # 命令行入口
│   └── __main__.py
├── examples/            # 示例游戏（demo.pyu / make_demo.py）
└── tests/               # 无第三方依赖的冒烟测试（直接 python 运行）
```

## 七、许可证

Apache License 2.0，Copyright 2026 oiiaio-web <3926580760@qq.com>。完整文本见 `LICENSE`。
