tkunity

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

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

一、安装

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

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

二、快速上手

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

在编辑器里：

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

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

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 工程：

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 对象：

{
  "meta":   { "tkunity_version": "2026.10.31", "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 原生能力，无第三方库）。

组件一览

四、导出 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

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。